Provided by: libgetdata-doc_0.11.0-6_all bug

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)