--- name: "gd_entry" section: "3" platform: "linux" package: "libgetdata-doc" version: "0.11.0-15" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gd_entry" --- # gd\_entry(3) retrieve a Dirfile field's metadata ## NAME gd\_entry — retrieve a Dirfile field's metadata ## SYNOPSIS **#include \** **int gd\_entry(DIRFILE \****dirfile***, const char \****field\_code***,** **gd\_entry\_t \****entry***);** ## DESCRIPTION The **gd\_entry**() function queries a [dirfile(5)](/dirfile/5.md) database specified by *dirfile* and retrieves the metadata associated with the field specified by *field\_code*. If *field\_code* contains a valid representation suffix, the suffix will be ignored. The *dirfile* argument must point to a valid DIRFILE object previously created by a call to [**gd\_open**(3)](/gd_open/3.md). The entry will be stored in the gd\_entry\_t structure indicated by the *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 *entry* filled by this function (including, depending on field type: *field*, elements of the *in\_fields* and *scalar* arrays, the **LINTERP** *table* member) will by dynamically allocated by **gd\_entry**(). Only strings provided by the gd\_entry\_t for the particular field type described will be allocated. By default, these strings are allocated using [**strdup**(3)](/strdup/3.md), but this can be changed by specifying an alternate memory manager via [**gd\_alloc\_funcs**(3)](/gd_alloc_funcs/3.md). The caller is responsible for deallocating these strings. The [**gd\_free\_entry\_strings**(3)](/gd_free_entry_strings/3.md) function is provided as a convenience to do this. If the entry's metadata contains scalar field codes which cannot be dereferenced, the associated numerical field parameter will be initialised to zero. In this case, the **GD\_EN\_CALC** flag in the returned entry object will *NOT* be set. The returned *entry* structure, including strings and their pointers may be freely modified by the caller. ## RETURN VALUE Upon successful completion, **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, **gd\_entry**() returns a negative-valued error code. Possible error codes are:\ .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\ .TP 8 **GD\_E\_BAD\_CODE** The field specified by *field\_code* was not found in the database.\ .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid. The error code is also stored in the **DIRFILE** object and may be retrieved after this function returns by calling [**gd\_error**(3)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md). ## 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: ``` typedef struct { ... const char *field; /* field code */ gd_entype_t field_type; /* field type */ int fragment_index; /* format fragment index */ unsigned flags; /* entry flags */ ... } gd_entry_t; ``` The *field* member is the field code of the entry (i.e. its string name). If the call to [**gd\_entry**(3)](/gd_entry/3.md) is successful, this will be the field name specified as part of the *field\_code* argument. The *field\_type* member indicates the field type of the entry. This is an integer type equal to one of the following symbols: - **GD\_BIT\_ENTRY**, **GD\_CARRAY\_ENTRY**, **GD\_CONST\_ENTRY**, **GD\_DIVIDE\_ENTRY**, **GD\_INDEX\_ENTRY**, **GD\_LINCOM\_ENTRY**, **GD\_LINTERP\_ENTRY**, **GD\_MPLEX\_ENTRY**, **GD\_MULTIPLY\_ENTRY**, **GD\_PHASE\_ENTRY**, **GD\_POLYNOM\_ENTRY**, **GD\_RAW\_ENTRY**, **GD\_RECIP\_ENTRY**, **GD\_SBIT\_ENTRY**, **GD\_STRING\_ENTRY**, **GD\_WINDOW\_ENTRY**. **GD\_INDEX\_ENTRY** is a special field type used only for the implicit *INDEX* field. The other entry types are explained in detail in [dirfile-format(5)](/dirfile-format/5.md). The *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 *fragment\_index* may be obtained by calling [**gd\_fragmentname**(3)](/gd_fragmentname/3.md). A value of zero for this field indicates that the field is defined in the primary fragment, the file called **format** in the root dirfile directory (see [dirfile(5)](/dirfile/5.md)). The *flags* member is a bitwise or'd collection of the following entry flags:\ .TP 8 **GD\_EN\_CALC** This bit is set only when the non-literal scalar parameter field codes specified in the *scalar* member have been resolved, and the corresponding numerical parameter have been initialised with these data. When one or more field code does not exist, or is invalid (ie. when [**gd\_validate**(3)](/gd_validate/3.md) would fail on the specified *field\_code* with the error **GD\_E\_BAD\_SCALAR**), then the unresolved numerical parameters are initialised to zero, and this flag is not be set. If the requested field does not allow non-literal scalar parameters (**CARRAY**, **CONST**, **DIVIDE**, **INDEX**, **LINTERP**, **MULTIPLY**, **STRING**), the value of this bit is unspecified.\ .TP 8 **GD\_EN\_COMPSCAL** For fields which permit complex valued parameters (**LINCOM**, **POLYNOM**, **RECIP**), this bit is set only when at least one parameter is complex valued. For other field types, the value of this bit is unspecified.\ .TP 8 **GD\_EN\_HIDDEN** This bit is set only when the field has been hidden by the **/HIDDEN** directive (see [**gd\_hidden**(3)](/gd_hidden/3.md)). Remaining fields in the gd\_entry\_t structure depend on the value of *field\_type*. Callers are advised to check *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. ### Scalar Parameter Members A gd\_entry\_t describing any field type which permits non-literal scalar field parameters (**BIT**, **LINCOM**, **MPLEX**, **PHASE**, **POLYNOM**, **RAW**, **RECIP**, **SBIT**, or **WINDOW**) will also provide: ``` 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; ``` Only certain elements of these arrays will be initialised: - • For **BIT** and **SBIT** fields, the first element corresponds to *bitnum* and the second to *numbits*. The remainder are uninitialised. - • For **LINCOM** fields, the first **GD\_MAX\_LINCOM** elements correspond to the slopes (*cm*) and the next **GD\_MAX\_LINCOM** elements correspond to the offsets (*cb*). Only the first *n\_fields* elements of these two sets are initialised. Notably, this means for *n\_fields* \< GD\_MAX\_LINCOM, there will be uninitialised elements in the middle of these arrays between the element corresponding to *cm*\[*n\_fields* - 1\] and the element corresponding to *cb*\[0\]. - • For **MPLEX** fields, the first element corresponds to *count\_val* and the second to *period*. The remainder are uninitialised. - • For **PHASE** fields, the first element corresponds to *shift*. The remainder are uninitialised. - • For **POLYNOM** fields, these arrays correspond with the co-efficients *ca*. Only the first *poly\_ord* + 1 elements are initialised. - • For **RAW** fields, the first element corresponds to *spf*. The remainder are uninitialised. - • For **RECIP** fields, the first element corresponds to *cdividend*. The remainder are uninitialised. - • For **WINDOW** fields, the first element corresponds to *threshold*. The remainder are uninitialised. The *scalar* parameters are NULL if a literal parameter was used, or else a field code specifying the scalar parameters. If an element of *scalar* specifies a **CARRAY** field, the corresponding *scalar\_ind* will indicate the element of the **CARRAY** used. For **CONST** fields, *scalar\_ind* will be -1. ### BIT and SBIT Members A gd\_entry\_t describing a **BIT** or **SBIT** entry, will also provide: ``` typedef struct { ... const char *in_fields[1]; /* input field code */ int bitnum; /* first bit */ int numbits; /* bit length */ ... } gd_entry_t; ``` The *in\_fields* member is an array of length one containing the input field code. The *bitnum* member indicates the number of the first bit (counted from zero) extracted from the input. If this value was specified as a scalar field code, this will be the numerical value of that field, and *scalar*\[0\] will contain the field code itself, otherwise *scalar*\[0\] will be NULL. The *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 *scalar*\[1\] will contain the field code itself, otherwise *scalar*\[1\] will be NULL. ### CARRAY Members A gd\_entry\_t describing a **CARRAY** entry, will also provide: ``` typedef struct { ... gd_type_t const_type; /* data type in format specification */ size_t array_len; /* length of array data */ ... } gd_entry_t; ``` The *const\_type* member indicates the data type of the constant value stored in the format file metadata. See [**gd\_getdata**(3)](/gd_getdata/3.md) for a list of valid values that a variable of type **gd\_type\_t** may take. The *array\_len* member gives the number of elements in the array. ### CONST Members A gd\_entry\_t describing a **CONST** entry, will also provide: ``` typedef struct { ... gd_type_t const_type; /* data type in format specification */ ... } gd_entry_t; ``` The *const\_type* member indicates the data type of the constant value stored in the format file metadata. See [**gd\_getdata**(3)](/gd_getdata/3.md) for a list of valid values that a variable of type **gd\_type\_t** may take. ### DIVIDE, INDIR, MULTIPLY, and SINDIR Members A gd\_entry\_t describing a **DIVIDE**, **INDIR**, **MULTIPLY**, or **SINDIR** entry, will also provide: ``` typedef struct { ... const char *in_fields[2]; /* input field codes */ ... } gd_entry_t; ``` The *in\_fields* member is an array of length two containing the input field codes. ### INDEX Members A gd\_entry\_t describing an **INDEX** entry, which is used only for the implicit *INDEX* field, provides no additional data. ### LINCOM Members A gd\_entry\_t describing a **LINCOM** entry, will also provide: ``` typedef struct { ... int n_fields; /* # of inputs */ const char *in_fields[GD_MAX_LINCOM]; /* input fields(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; ``` The *n\_fields* member indicates the number of input fields. It will be between one and **GD\_MAX\_LINCOM** inclusive. **GD\_MAX\_LINCOM** is defined in getdata.h as the maximum number of input fields permitted by a **LINCOM**. The *in\_fields* member is an array of length **GD\_MAX\_LINCOM** containing the input field code(s). Only the first *n\_fields* elements of this array are initialised. The remaining elements contain uninitialised data. The *cm* and *cb* members are arrays of the scale factor(s) and offset term(s) for the **LINCOM**. Only the first *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 *cm*\[*i*\] will be stored in *scalar*\[*i*\] and the field code associated with *cb*\[*i*\] will be stored in *scalar*\[*i* + **GD\_MAX\_LINCOM**\]. Otherwise the corresponding *scalar* member will be NULL. See **NOTES** below on changes to the declaration of *cm* and *cb* when using the C89 GetData API. The elements of *m* and *b* are the real parts of the corresponding elements of *cm* and *cb*. ### LINTERP Members A gd\_entry\_t describing a **LINTERP** entry, will also provide: ``` typedef struct { ... const char *table /* linterp table filename */ const char *in_fields[1]; /* input field code */ ... } gd_entry_t; ``` The *table* member is the pathname to the look up table on disk. This the path as it appars in the format specification. It may be a path relative to the fragment directory. For an canonicalised, absolute version of this path, see [**gd\_linterp\_tablename**(3)](/gd_linterp_tablename/3.md). The *in\_fields* member is an array of length one containing the input field code. ### MPLEX Members A gd\_entry\_t describing a **MPLEX** entry, will also provide: ``` typedef struct { ... const char *in_fields[2]; /* input field codes */ int count_val; /* value of the multiplex index */ int period; /* samples between successive indices */ ... } gd_entry_t; ``` The *in\_fields* member contains the field codes of the input field (element 0) and the multiplex index field (element 1). The *count\_val* member is the value of the multiplex index field when the output field is stored in the input field. The *period* member is the number of samples between successive occurrances of *count\_val* in the index vector, or zero, if this is not known or constant. This is only used to determine how far to look back for a starting value for the output field; see [**gd\_mplex\_lookback**(3)](/gd_mplex_lookback/3.md). ### PHASE Members A gd\_entry\_t describing a **PHASE** entry, will also provide: ``` typedef struct { ... const char *in_fields[1]; /* input field code */ gd_int64_t shift; /* phase shift */ ... } gd_entry_t; ``` The *in\_fields* member is an array of length one containing the input field code. The *shift* member indicates the shift in samples. The **gd\_int64\_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 *scalar*\[0\] will contain the field code itself, otherwise *scalar*\[0\] will be NULL. ### POLYNOM Members A gd\_entry\_t describing a **POLYNOM** entry, will also provide: ``` typedef struct { ... int poly_ord; /* polynomial order */ const char *in_fields[1]; /* input field(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; ``` The *poly\_ord* member indicates the order of the polynomial. It will be between one and **GD\_MAX\_POLY\_ORD** inclusive. **GD\_MAX\_POLY\_ORD** is defined in getdata.h as the maximum order of polynomial permitted by a **POLYNOM**. The *in\_fields* member is an array of length one containing the input field code. The *ca* members are arrays of the co-efficient(s) for the **POLYNOM**. Only the first *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 *ca*\[*i*\] will be stored in *scalar*\[*i*\]. Otherwise the corresponding *scalar* member will be NULL. See **NOTES** below on changes to the declaration of *ca* when using the C89 GetData API. The elements of *a* are the real parts of the corresponding elements of *ca*. ### RAW Members A gd\_entry\_t describing a **RAW** entry, will also provide: ``` typedef struct { ... unsigned int spf; /* samples per frame on disk */ gd_type_t data_type; /* data type on disk */ ... } gd_entry_t; ``` The *spf* member contains the samples per frame of the binary data on disk. If this value was specified as a scalar field code, this will be the numerical value of that field, and *scalar*\[0\] will contain the field code itself, otherwise *scalar*\[0\] will be NULL. The *data\_type* member indicates the data type of the binary data on disk. See [**gd\_getdata**(3)](/gd_getdata/3.md) for a list of valid values that a variable of type **gd\_type\_t** may take. ### RECIP Members A gd\_entry\_t describing a **RECIP** entry, will also provide: ``` typedef struct { ... const char *in_fields[1]; /* input field code */ double complex cdividend; /* scalar dividend */ double dividend; /* scalar dividend */ ... } gd_entry_t; ``` The *in\_fields* member is an array of length one containing the input field code. The *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 *scalar*\[0\] will contain the field code itself, otherwise *scalar*\[0\] will be NULL. The *dividend* member contains the real part of *cdividend*. ### STRING Members A gd\_entry\_t describing a **STRING** entry provides no additional data. ### WINDOW Members A gd\_entry\_t describing a **WINDOW** entry, will also provide: ``` typedef struct { ... const char *in_fields[2]; /* input field codes */ gd_windop_t windop; /* comparison operator */ gd_triplet_t threshold; /* the value compared against */ ... } gd_entry_t; ``` The *in\_fields* member contains the field codes of the input field (element 0) and the check field (element 1). The *windop* member equals one of the following symbols, indicating the particular comparison performed on the check field:\ .TP 8 **GD\_WINDOP\_EQ** data are extracted when the check field equals *threshold*;\ .TP 8 **GD\_WINDOP\_GE** data are extracted when the check field is greater than or equal to *threshold*;\ .TP 8 **GD\_WINDOP\_GT** data are extracted when the check field is strictly greater than *threshold*;\ .TP 8 **GD\_WINDOP\_LE** data are extracted when the check field is less than or equal to *threshold*;\ .TP 8 **GD\_WINDOP\_LT** data are extracted when the check field is strictly less than *threshold*;\ .TP 8 **GD\_WINDOP\_NE** data are extracted when the check field is not equal to *threshold*;\ .TP 8 **GD\_WINDOP\_SET** data are extracted when at least one bit in *threshold* is also set in the check field;\ .TP 8 **GD\_WINDOP\_CLR** data are extracted when at least one bit in *threshold* is not set in the check field. The *threshold* is the value against which the check field is compared. The **gd\_triplet\_t** type is defined as: ``` typedef union { gd_int64_t i; gd_uint64_t u; double r; } gd_triplet_t; ``` The particular element of the union to use depends on the value of *windop:* - • For **GD\_WINDOP\_EQ** and **GD\_WINDOP\_NE**, the signed integer element, *threshold***.***i,* is set; - • For **GD\_WINDOP\_SET** and **GD\_WINDOP\_CLR**, the unsigned integer element, *threshold***.***u,* is set; - • For all other values of *windop*, the floating point element, *threshold***.***r,* is set. ## NOTES When using the C89 GetData API (by defining **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. | | | | | | --- | --- | --- | --- | | **C99 API** | | int | bitnum | int | u.bit.bitnum | | int | numbits | int | u.bit.numbits | | int | n\_fields | int | u.lincom.n\_fields | | double complex | cm\[\] | double | u.lincom.cm\[\]\[2\] | | double | m\[\] | double | u.lincom.m\[\] | | double complex | cb\[\] | double | u.lincom.cb\[\]\[2\] | | double | b\[\] | double | u.lincom.b\[\] | | const char\* | table | const char\* | u.linterp.table | | int | count\_val | int | u.mplex.count\_val | | int | period | int | u.mplex.period | | gd\_int64\_t | shift | gd\_int64\_t | u.phase.shift | | int | poly\_ord | int | u.polynom.poly\_ord | | double complex | ca\[\] | double | u.polynom.ca\[\]\[2\] | | double | a\[\] | double | u.polynom.a\[\] | | unsigned int | spf | unsigned int | u.raw.spf | | gd\_type\_t | data\_type | gd\_type\_t | u.raw.data\_type | | double complex | 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 | | gd\_windop\_t | windop | gd\_windop\_t | u.window.windop | | gd\_triplet\_t | threshold | gd\_triplet\_t | u.window.threshold | 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. ## HISTORY The **get\_entry**() function appeared in GetData-0.3.0. In GetData-0.7.0, this function was renamed to **gd\_entry**(). In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. ### Changes to the gd\_entry\_t structure Field-type specific members have been added to the structure as support for those field types have been introduced to the library: - • **BIT**, **LINCOM**, **LINTERP**, **MULTIPLY**, **PHASE**, and **RAW** were supported in GetData-0.3.0 (Dirfile Standards Version 5). - • **CONST** and **STRING** entries were introduced in GetData-0.4.0 (Dirfile Standards Version 6); this is also the first version that treats *INDEX* as a normal field. In earlier versions, trying to retrieve the metadata for the *INDEX* field would fail. - • **POLYNOM** and **SBIT** entries were introduced in GetData-0.6.0 (Dirfile Standards Version 7). - • **CARRAY**, **DIVIDE**, and **RECIP** entries were introduced in GetData-0.7.0 (Dirfile Standards Version 8). - • **MPLEX** and **WINDOW** entries were introduced in GetData-0.8.0 (Dirfile Standards Version 9). - • **INDIR**, **SARRAY**, and **SINDIR** entries were introduced in GetData-0.10.0 (Dirfile Standards Version 10). The *scalar* member appeared in GetData-0.6.0. This release also introduced the complex-valued scalar members (*cm*, *cb*, &c.) The *scalar\_ind* member appeared in GetData-0.7.0. This was also the first release with a working ANSI C (C89) conforming alternate definition. Before Getdata-0.8.4, the *period* member for **MPLEX** data was named *count\_max*. Before GetData-0.9.0, the *flags* member is missing. In it's place was: int comp\_scal; /\* Scalar parameters are complex-valued \*/ which was non-zero to indicate complex-valued parameters, which is now indicated by the **GD\_EN\_COMPSCAL** flag. ## SEE ALSO [dirfile(5)](/dirfile/5.md), [**gd\_alloc\_funcs**(3)](/gd_alloc_funcs/3.md), [**gd\_cbopen**(3)](/gd_cbopen/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_field\_list**(3)](/gd_field_list/3.md), [**gd\_fragmentname**(3)](/gd_fragmentname/3.md), [**gd\_free\_entry\_strings**(3)](/gd_free_entry_strings/3.md), [**gd\_linterp\_tablename**(3)](/gd_linterp_tablename/3.md) [**gd\_mplex\_lookback**(3)](/gd_mplex_lookback/3.md), [**gd\_raw\_filename**(3)](/gd_raw_filename/3.md), [**gd\_validate**(3)](/gd_validate/3.md)