Provided by: libgetdata-doc_0.11.0-6_all 
NAME
gd_entry — retrieve a Dirfile field's metadata
SYNOPSIS
#include <getdata.h>
int gd_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t *entry);
DESCRIPTION
The gd_entry() function queries a dirfile(5) 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).
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), but this can be changed by specifying an alternate memory
manager via gd_alloc_funcs(3). The caller is responsible for deallocating these strings.
The gd_free_entry_strings(3) 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:
GD_E_ALLOC
The library was unable to allocate memory.
GD_E_BAD_CODE
The field specified by field_code was not found in the database.
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). A descriptive error string for the error may be
obtained by calling gd_error_string(3).
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) 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).
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). 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)).
The flags member is a bitwise or'd collection of the following entry flags:
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) 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.
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.
GD_EN_HIDDEN
This bit is set only when the field has been hidden by the /HIDDEN directive (see
gd_hidden(3)).
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) 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) 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).
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).
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) 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:
GD_WINDOP_EQ
data are extracted when the check field equals threshold;
GD_WINDOP_GE
data are extracted when the check field is greater than or equal to threshold;
GD_WINDOP_GT
data are extracted when the check field is strictly greater than threshold;
GD_WINDOP_LE
data are extracted when the check field is less than or equal to threshold;
GD_WINDOP_LT
data are extracted when the check field is strictly less than threshold;
GD_WINDOP_NE
data are extracted when the check field is not equal to threshold;
GD_WINDOP_SET
data are extracted when at least one bit in threshold is also set in the check
field;
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 C89 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), gd_alloc_funcs(3), gd_cbopen(3), gd_error(3), gd_error_string(3),
gd_field_list(3), gd_fragmentname(3), gd_free_entry_strings(3), gd_linterp_tablename(3)
gd_mplex_lookback(3), gd_raw_filename(3), gd_validate(3)