gd_entry(3) GETDATA gd_entry(3)NAMEgd_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 returns 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 avail‐
able 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 (variously, depending
on field type: field, the elements of the in_fields[] array, table; see
below) will by dynamically allocated by 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 de‐
scribed will be allocated. These strings should be de-allocated with
free(3) by the caller once they are no longer needed. The gd_free_en‐
try_strings(3) function is provided as a convenience to do this.
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 sup‐
plied gd_entry_t buffer is not modified. In this case, gd_entry() re‐
turns -1 and sets the dirfile error to a non-zero error value. Possi‐
ble error values 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 data‐
base.
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
GD_E_BAD_REPR
The representation suffix specified in field_code was not
recognised.
GD_E_BAD_SCALAR
A scalar parameter used in the definition of the field was in‐
valid.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to 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 */
...
} 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-for‐
mat(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)).
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, attempt‐
ing 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 corre‐
spond 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-effi‐
cients ca. Only the first poly_ord + 1 elements are ini‐
tialised.
· For RAW fields, the first element corresponds to spf. The re‐
mainder 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 con‐
tain 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.
INDEX Members
A gd_entry_t describing an INDEX entry, which is used only for the im‐
plicit 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 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;
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 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 cm and cb equal the corresponding elements of m and b.)
members.)
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 ar‐
ray 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 ele‐
ments 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 count_vals */
...
} gd_entry_t;
The in_fields member contains the field codes of the input field (ele‐
ment 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 occur‐
rances 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).
MULTIPLY and DIVIDE Members
A gd_entry_t describing a MULTIPLY or DIVIDE 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.
PHASE Members
A gd_entry_t describing a PHASE entry, will also provide:
typedef struct {
...
const char *in_fields[1]; /* input field code */
gd_shift_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_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 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 */
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;
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 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 ca equal the corresponding elements of a.)
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 {
...
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;
The 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, cdividend
equals dividend.)
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 di‐
vision. 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 mem‐
ber 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 (ele‐
ment 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 thresh‐
old;
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 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 win‐
dop:
· 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 ele‐
ment, 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[3] double u.lincom.cm[3][2]
double m[3] double u.lincom.m[3]
double complex cb[3] double u.lincom.cb[3][2]
double b[3] double u.lincom.b[3]
const char* table const char* u.linterp.table
int count_val int u.mplex.count_val
int period int u.mplex.period
gd_shift_t shift gd_shift_t u.phase.shift
int poly_ord int u.polynom.poly_ord
double complex ca[3] double u.polynom.ca[3][2]
double a[3] double u.polynom.a[3]
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.
SEE ALSOdirfile(5), gd_free_entry_strings(3), gd_cbopen(3), gd_error(3), gd_er‐
ror_string(3), gd_field_list(3), gd_fragmentname(3), gd_linterp_table‐
name(3)gd_mplex_lookback(3), gd_raw_filename(3)Version 0.8.4 3 April 2013 gd_entry(3)
