.\" gd_entry.3. The gd_entry man page. .\" .\" Copyright (C) 2008, 2009, 2010 D. V. Wiebe .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" .\" This file is part of the GetData project. .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover .\" Texts. A copy of the license is included in the `COPYING.DOC' file .\" as part of this distribution. .\" .TH gd_entry 3 "3 November 2010" "Version 0.7.0" "GETDATA" .SH NAME gd_entry \(em retrieve a dirfile field's metadata .SH SYNOPSIS .B #include .HP .nh .ad l .BI "int gd_entry(DIRFILE *" dirfile ", const char *" field_code , .BI "gd_entry_t *" entry ); .hy .ad n .SH DESCRIPTION The .BR gd_entry () function queries a dirfile(5) database specified by .I dirfile and returns the metadata associated with the field specified by .IR field_code . If .I field_code contains a valid representation suffix, the suffix will be ignored. The .I dirfile argument must point to a valid DIRFILE object previously created by a call to .BR gd_open (3). The entry will be stored in the gd_entry_t structure indicated by the .I entry argument, which must be allocated by the caller. Members available in this structure depend on the field type of the field queried. See below for a complete description of this data type. Strings members in .I entry filled by this function (variously, depending on field type: .IR field ", the elements of the " in_fields "[] array, " table ; see below) will by dynamically allocated by .BR gd_entry () and should not point to allocated memory locations before calling this function. Only strings provided by the gd_entry_t for the particular field type described will be allocated. These strings should be de-allocated with .BR free (3) by the caller once they are no longer needed. The .BR gd_free_entry_strings (3) function is provided as a convenience to do this. The returned .I entry structure, including strings and their pointers may be freely modified by the caller. .SH RETURN VALUE Upon successful completion, .BR gd_entry () returns zero, and writes the field metadata in the supplied gd_entry_t buffer. On error, the supplied gd_entry_t buffer is not modified. In this case, .BR gd_entry () returns -1 and sets the dirfile error to a non-zero error value. Possible error values are: .TP 8 .B GD_E_BAD_CODE The field specified by .I field_code was not found in the database. .TP .B GD_E_BAD_DIRFILE The supplied dirfile was invalid. .TP .B GD_E_BAD_REPR The representation suffix specified in .I field_code was not recognised. .TP .B GD_E_BAD_SCALAR A scalar parameter used in the definition of the field was invalid. .PP The dirfile error may be retrieved by calling .BR gd_error (3). A descriptive error string for the last error encountered can be obtained from a call to .BR gd_error_string (3). .SH THE ENTRY TYPE Members available in the gd_entry_t structure depend on the field type described. All gd_entry_t objects are guaranteed to have at least: .PP .in +4n .nf .fam C typedef struct { ... const char *field; /* field code */ gd_entype_t field_type; /* field type */ int fragment_index; /* format fragment index */ ... } gd_entry_t; .fam .fi .in .PP The .I field member is the field code of the entry (i.e. its string name). If the call to .BR gd_entry (3) is successful, this will be the field name specified as part of the .I field_code argument. .PP The .I field_type member indicates the field type of the entry. This is an integer type equal to one of the following symbols: .IP .nh .ad l .BR GD_BIT_ENTRY ", " GD_CARRAY_ENTRY ", " GD_CONST_ENTRY ", " GD_DIVIDE_ENTRY , .BR GD_INDEX_ENTRY ", " GD_LINCOM_ENTRY ", " GD_LINTERP_ENTRY , .BR GD_MULTIPLY_ENTRY ", " GD_PHASE_ENTRY ", " GD_POLYNOM_ENTRY , .BR GD_RAW_ENTRY ", " GD_RECIP_ENTRY ", " GD_SBIT_ENTRY ", " GD_STRING_ENTRY . .ad n .hy .PP .B GD_INDEX_ENTRY is a special field type used only for the implicit .I INDEX field. The meaning of the other symbols should be self-explanatory. .PP The .I fragment_index member indicates the format specification fragment in which this field is defined. This is an integer index to the Dirfile's list of parsed format specification fragments. The name of the file corresponding to .I fragment_index may be obtained by calling .BR gd_fragmentname (3). A value of zero for this field indicates that the field is defined in the primary fragment, the file called .B format in the root dirfile directory (see .IR dirfile (5)). .PP Remaining fields in the gd_entry_t structure depend on the value of .IR field_type . Callers are advised to check .I field_type before attempting to access the remaining members. Members for different field types may be stored in the same physical location in core. Accordingly, attempting to access a member not declared for the appropriate field type will have unspecified results. .SS Scalar Parameter Members A gd_entry_t describing any field type which permits non-literal scalar field parameters .RB ( BIT ", " LINCOM ", " PHASE ", " POLYNOM ", " RECIP ", " RAW ", or " SBIT ) will also provide: .PP .in +4n .nf .fam C typedef struct { ... const char *scalar[GD_MAX_POLY_ORD + 1]; /* param. fields */ int scalar_ind[GD_MAX_POLY_ORD + 1]; /* CARRAY indices */ ... } gd_entry_t; .fam .fi .in .PP Only certain elements of these arrays will be initialised: .IP \(bu 4 For .B BIT and .B SBIT fields, the first element corresponds to .I bitnum and the second to .IR numbits . The remainder are uninitialised. .IP \(bu 4 For .B LINCOM fields, the first .B GD_MAX_LINCOM elements correspond to the slopes .RI ( cm ) and the next .B GD_MAX_LINCOM elements correspond to the offsets .RI ( cb ). Only the first .I n_fields elements of these two sets are initialised. Notably, this means for .I n_fields < GD_MAX_LINCOM, there will be uninitialised elements in the middle of these arrays between the element corresponding to .IR cm [ n_fields - 1] and the element corresponding to .IR cb [0]. .IP \(bu 4 For .B PHASE fields, the first element corresponds to .IR shift . The remainder are unitialised. .IP \(bu 4 For .B POLYNOM fields, these arrays correspond with the co-efficients .IR ca . Only the first .I poly_ord + 1 elements are initialised. .IP \(bu 4 For .B RECIP fields, the first element corresponds to .IR cdividend . The remainder are unitialised. .IP \(bu 4 For .B RAW fields, the first element corresponds to .IR spf . The remainder are unitialised. .PP The .I scalar parameters are NULL if a literal parameter was used, or else a field code specifying the scalar parameters. .PP If an element of .I scalar specifies a .B CARRAY field, the corresponding .I scalar_ind will indicate the element of the .B CARRAY used. For .B CONST fields, .I scalar_ind will be -1. .SS BIT and SBIT Members A gd_entry_t describing a .B BIT or .B SBIT entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... const char *in_fields[1]; /* input field code */ gd_bit_t bitnum; /* first bit */ gd_bit_t numbits; /* bit length */ ... } gd_entry_t; .fam .fi .in .PP The .I in_fields member is an array of length one containing the input field code. .PP The .I bitnum member indicates the number of the first bit (counted from zero) extracted from the input. The .I gd_bit_t type is a signed 16-bit integer type. If this value was specified as a scalar field code, this will be the numerical value of that field, and .IR scalar [0] will contain the field code itself, otherwise .IR scalar [0] will be NULL. .PP The .I numbits member indicates the number of bits which are extracted from the input. If this value was specified as a scalar field code, this will be the numerical value of that field, and .IR scalar [1] will contain the field code itself, otherwise .IR scalar [1] will be NULL. .SS CARRAY Members A gd_entry_t describing a .B CARRAY entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... gd_type_t const_type; /* data type in format specification */ size_t array_len; /* length of array data */ ... } gd_entry_t; .fam .fi .in .PP The .I const_type member indicates the data type of the constant value stored in the format file metadata. See .BR gd_getdata (3) for a list of valid values that a variable of type .B gd_type_t may take. .PP The .I array_len member gives the number of elements in the array. .SS CONST Members A gd_entry_t describing a .B CONST entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... gd_type_t const_type; /* data type in format specification */ ... } gd_entry_t; .fam .fi .in .PP The .I const_type member indicates the data type of the constant value stored in the format file metadata. See .BR gd_getdata (3) for a list of valid values that a variable of type .B gd_type_t may take. .SS INDEX Members A gd_entry_t describing an .B INDEX entry, which is used only for the implicit .I INDEX field, provides no additional data. .SS LINCOM Members A gd_entry_t describing a .B LINCOM entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... int n_fields; /* # of input fields */ int comp_scal; /* complex scalar flag */ const char *in_fields[GD_MAX_LINCOM]; /* input field code(s) */ double complex cm[GD_MAX_LINCOM]; /* scale factor(s) */ double m[GD_MAX_LINCOM]; /* scale factor(s) */ double complex cb[GD_MAX_LINCOM]; /* offset terms(s) */ double b[GD_MAX_LINCOM]; /* offset terms(s) */ ... } gd_entry_t; .fam .fi .in .PP The .I n_fields member indicates the number of input fields. It will be between one and .B GD_MAX_LINCOM inclusive, which is defined in getdata.h to the maximum number of input fields permitted by a .BR LINCOM . .PP The .I comp_scal member is non-zero if any of the scale factors or offset terms have a non-zero imaginary part. (That is, if comp_scal is zero, the elements of .IR cm \~and\~ cb equal the corresponding elements of .IR m \~and\~ b .) members.) .PP The .I in_fields member is an array of length .B GD_MAX_LINCOM containing the input field code(s). Only the first .I n_fields elements of this array are initialised. The remaining elements contain uninitialised data. .PP The .I cm and .I cb members are arrays of the scale factor(s) and offset term(s) for the .BR LINCOM . Only the first .I n_fields elements of these array contain meaningful data. If any of these values were specified as a scalar field code, this will be the numerical value of that field. The field code corresponding to .IR cm [ i ] will be stored in .IR scalar [ i ] and the field code associated with .IR cb [ i ] will be stored in .IR scalar [ i + .BR GD_MAX_LINCOM ]. Otherwise the corresponding .I scalar member will be NULL. See .B NOTES below on changes to the declaration of .I cm and .I cb when using the C89 GetData API. .PP The elements of .I m and .I b are the real parts of the corresponding elements of .I cm and .IR cb . .SS LINTERP Members A gd_entry_t describing a .B LINTERP entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... const char *table /* linterp table filename */ const char *in_fields[1]; /* input field code */ ... } gd_entry_t; .fam .fi .in .PP The .I table member is the pathname to the look up table on disk. .PP The .I in_fields member is an array of length one containing the input field code. .SS MULTIPLY and DIVIDE Members A gd_entry_t describing a .B MULTIPLY or .B DIVIDE entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... const char *in_fields[2]; /* input field codes */ ... } gd_entry_t; .fam .fi .in .PP The .I in_fields member is an array of length two containing the input field codes. .SS PHASE Members A gd_entry_t describing a .B PHASE entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... const char *in_fields[1]; /* input field code */ gd_shift_t shift; /* phase shift */ ... } gd_entry_t; .fam .fi .in .PP The .I in_fields member is an array of length one containing the input field code. .PP The .I shift member indicates the shift in samples. The .I gd_shift_t type is a 64-bit signed integer type. A positive value indicates a shift forward in time (towards larger frame numbers). If this value was specified as a scalar field code, this will be the numerical value of that field, and .IR scalar [0] will contain the field code itself, otherwise .IR scalar [0] will be NULL. .SS POLYNOM Members A gd_entry_t describing a .B POLYNOM entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... int poly_ord; /* polynomial order */ int comp_scal; /* complex scalar flag */ const char *in_fields[1]; /* input field code(s) */ double complex ca[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */ double a[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */ ... } gd_entry_t; .fam .fi .in .PP The .I poly_ord member indicates the order of the polynomial. It will be between one and .B GD_MAX_POLY_ORD inclusive, which is defined in getdata.h to the maximum order of polynomial permitted by a .BR POLYNOM . .PP The .I comp_scal member is non-zero if any of the co-efficients have a non-zero imaginary part. (That is, if comp_scal is zero, the elements of .I ca equal the corresponding elements of .IR a .) .PP The .I in_fields member is an array of length one containing the input field code. .PP The .I ca members are arrays of the co-efficient(s) for the .BR POLYNOM . Only the first .I poly_ord + 1 elements of this array contains meaningful data. If any of these values were specified as a scalar field code, this will be the numerical value of that field. The field code corresponding to .IR ca [ i ] will be stored in .IR scalar [ i ]. Otherwise the corresponding .I scalar member will be NULL. See .B NOTES below on changes to the declaration of .I ca when using the C89 GetData API. .PP The elements of .I a are the real parts of the corresponding elements of .IR ca . .SS RECIP Members A gd_entry_t describing a .B RECIP entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... int comp_scal; /* complex scalar flag */ const char *in_fields[1]; /* input field code */ double complex cdividend; /* scalar dividend */ double dividend; /* scalar dividend */ ... } gd_entry_t; .fam .fi .in .PP The .I comp_scal member is non-zero if any of the co-efficients have a non-zero imaginary part. (That is, if comp_scal is zero, .I cdividend equals .IR dividend .) .PP The .I in_fields member is an array of length one containing the input field code. .PP The .I cdividend member provides the constant dividend of the computed division. If this value was specified as a scalar field code, this will be the numerical value of that field, and .IR scalar [0] will contain the field code itself, otherwise .IR scalar [0] will be NULL. The .I dividend member contains the real part of .IR cdividend . .SS RAW Members A gd_entry_t describing a .B RAW entry, will also provide: .PP .in +4n .nf .fam C typedef struct { ... gd_spf_t spf; /* samples per frame on disk */ gd_type_t data_type; /* data type on disk */ ... } gd_entry_t; .fam .fi .in .PP The .I spf member contains the samples per frame of the binary data on disk. The .I gd_spf_t type is an unsigned 16-bit integer type. If this value was specified as a scalar field code, this will be the numerical value of that field, and .IR scalar [0] will contain the field code itself, otherwise .IR scalar [0] will be NULL. .PP The .I data_type member indicates the data type of the binary data on disk. See .BR gd_getdata (3) for a list of valid values that a variable of type .B gd_type_t may take. .SS STRING Members A gd_entry_t describing a .B STRING entry provides no additional data. .SH NOTES When using the C89 GetData API (by defining .B GD_C89_API before including getdata.h), the data types and names of several of the entry parameters are different. The following table lists the correspondences between members in the C99 and C89 APIs. .TS center tab(|); cbscbs rlrl. C99 API|C89 API gd_spf_t|spf|gd_spf_t|u.raw.spf gd_type_t|data_type|gd_type_t|u.raw.data_type int|n_fields|int|u.lincom.n_fields double compex|cm[3]|double|u.lincom.cm[3][2] double|m[3]|double|u.lincom.m[3] double compex|cb[3]|double|u.lincom.cb[3][2] double|b[3]|double|u.lincom.b[3] int|poly_ord|int|u.polynom.poly_ord double compex|ca[3]|double|u.polynom.ca[3][2] double|a[3]|double|u.polynom.a[3] const char*|table|const char*|u.linterp.table gd_bit_t|bitnum|gd_bit_t|u.bit.bitnum gd_bit_t|numbits|gd_bit_t|u.bit.numbits gd_shift_t|shift|gd_shift_t|u.phase.shift double compex|cdividend|double|u.recip.cdividend[2] double|dividend|double|u.recip.dividend gd_type_t|const_type|gd_type_t|u.scalar.const_type size_t|array_len|size_t|u.scalar.array_len .TE .PP In the case of complex valued data in the C89 API, the first element of the two element array is the real part of the complex number, and the second element is the imaginary part. .SH SEE ALSO .BR dirfile (5), .BR gd_free_entry_strings (3), .BR gd_cbopen (3), .BR gd_error (3), .BR gd_error_string (3), .BR gd_field_list (3), .BR gd_fragmentname (3), .BR gd_getdata (3), .BR gd_raw_filename (3)