1
2
3
4
5
6
7
8
9gd_entry(3)                         GETDATA                        gd_entry(3)
10
11
12

NAME

14       gd_entry — retrieve a Dirfile field's metadata
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t
21              *entry);
22
23

DESCRIPTION

25       The gd_entry() function queries  a  dirfile(5)  database  specified  by
26       dirfile  and retrieves the metadata associated with the field specified
27       by field_code.  If field_code contains a valid  representation  suffix,
28       the suffix will be ignored.
29
30       The  dirfile  argument  must point to a valid DIRFILE object previously
31       created by a call to gd_open(3).
32
33       The entry will be stored in the gd_entry_t structure indicated  by  the
34       entry  argument, which must be allocated by the caller.  Members avail‐
35       able in this structure depend on the field type of the  field  queried.
36       See below for a complete description of this data type.
37
38       Strings  members in entry filled by this function (including, depending
39       on field type: field, elements of the in_fields and scalar arrays,  the
40       LINTERP table member) will by dynamically allocated by gd_entry().  On‐
41       ly strings provided by the gd_entry_t for the particular field type de‐
42       scribed will be allocated.  By default, these strings are allocated us‐
43       ing strdup(3), but this can be changed by specifying an alternate memo‐
44       ry  manager via gd_alloc_funcs(3).  The caller is responsible for deal‐
45       locating these strings.  The gd_free_entry_strings(3) function is  pro‐
46       vided as a convenience to do this.
47
48       If  the  entry's  metadata  contains scalar field codes which cannot be
49       dereferenced, the associated numerical field  parameter  will  be  ini‐
50       tialised  to  zero.   In this case, the GD_EN_CALC flag in the returned
51       entry object will NOT be set.
52
53       The returned entry structure, including strings and their pointers  may
54       be freely modified by the caller.
55
56

RETURN VALUE

58       Upon  successful  completion,  gd_entry()  returns  zero and writes the
59       field metadata in the supplied gd_entry_t buffer.  On error,  the  sup‐
60       plied  gd_entry_t buffer is not modified.  In this case, gd_entry() re‐
61       turns a negative-valued error code.  Possible error codes are:
62
63       GD_E_ALLOC
64               The library was unable to allocate memory.
65
66       GD_E_BAD_CODE
67               The field specified by field_code was not found  in  the  data‐
68               base.
69
70       GD_E_BAD_DIRFILE
71               The supplied dirfile was invalid.
72
73       The  error  code  is  also  stored in the DIRFILE object and may be re‐
74       trieved after this function returns by calling gd_error(3).  A descrip‐
75       tive   error   string   for  the  error  may  be  obtained  by  calling
76       gd_error_string(3).
77
78

THE ENTRY TYPE

80       Members available in the gd_entry_t structure depend on the field  type
81       described.  All gd_entry_t objects are guaranteed to have at least:
82
83              typedef struct {
84                ...
85
86                const char  *field;          /* field code */
87                gd_entype_t  field_type;     /* field type */
88                int          fragment_index; /* format fragment index */
89                unsigned     flags;          /* entry flags */
90
91                ...
92              } gd_entry_t;
93
94       The field member is the field code of the entry (i.e. its string name).
95       If the call to gd_entry(3) is successful, this will be the  field  name
96       specified as part of the field_code argument.
97
98       The  field_type  member indicates the field type of the entry.  This is
99       an integer type equal to one of the following symbols:
100
101              GD_BIT_ENTRY, GD_CARRAY_ENTRY, GD_CONST_ENTRY, GD_DIVIDE_ENTRY,
102              GD_INDEX_ENTRY, GD_LINCOM_ENTRY, GD_LINTERP_ENTRY,
103              GD_MPLEX_ENTRY, GD_MULTIPLY_ENTRY, GD_PHASE_ENTRY,
104              GD_POLYNOM_ENTRY, GD_RAW_ENTRY, GD_RECIP_ENTRY, GD_SBIT_ENTRY,
105              GD_STRING_ENTRY, GD_WINDOW_ENTRY.
106
107       GD_INDEX_ENTRY is a special field type used only for the implicit INDEX
108       field.   The  other entry types are explained in detail in dirfile-for‐
109       mat(5).
110
111       The fragment_index member indicates the format  specification  fragment
112       in  which  this  field  is  defined.   This  is an integer index to the
113       Dirfile's list of parsed format specification fragments.  The  name  of
114       the  file  corresponding  to  fragment_index may be obtained by calling
115       gd_fragmentname(3).  A value of zero for this field indicates that  the
116       field is defined in the primary fragment, the file called format in the
117       root dirfile directory (see dirfile(5)).
118
119       The flags member is a bitwise or'd collection of  the  following  entry
120       flags:
121
122       GD_EN_CALC
123               This  bit  is  set  only  when the non-literal scalar parameter
124               field codes specified in the scalar member have been  resolved,
125               and the corresponding numerical parameter have been initialised
126               with these data.  When one or more field code does  not  exist,
127               or is invalid (ie. when gd_validate(3) would fail on the speci‐
128               fied field_code with the error GD_E_BAD_SCALAR), then the unre‐
129               solved  numerical  parameters are initialised to zero, and this
130               flag is not be set.  If the requested field does not allow non-
131               literal   scalar  parameters  (CARRAY,  CONST,  DIVIDE,  INDEX,
132               LINTERP, MULTIPLY, STRING), the value of this bit  is  unspeci‐
133               fied.
134
135       GD_EN_COMPSCAL
136               For  fields  which  permit  complex  valued parameters (LINCOM,
137               POLYNOM, RECIP), this bit is set only when at least one parame‐
138               ter  is  complex  valued.   For other field types, the value of
139               this bit is unspecified.
140
141       GD_EN_HIDDEN
142               This bit is set only when the field  has  been  hidden  by  the
143               /HIDDEN directive (see gd_hidden(3)).
144
145       Remaining  fields  in  the  gd_entry_t structure depend on the value of
146       field_type.  Callers are advised to check field_type before  attempting
147       to access the remaining members.  Members for different field types may
148       be stored in the same physical location in core.  Accordingly, attempt‐
149       ing to access a member not declared for the appropriate field type will
150       have unspecified results.
151
152
153   Scalar Parameter Members
154       A gd_entry_t describing any field type which permits non-literal scalar
155       field parameters (BIT, LINCOM, MPLEX, PHASE, POLYNOM, RAW, RECIP, SBIT,
156       or WINDOW) will also provide:
157
158              typedef struct {
159                ...
160
161                const char *scalar[GD_MAX_POLY_ORD + 1];   /* param. fields */
162                int         scalar_ind[GD_MAX_POLY_ORD + 1];
163                                                          /* CARRAY indices */
164
165                ...
166              } gd_entry_t;
167
168       Only certain elements of these arrays will be initialised:
169
170       ·      For BIT and SBIT fields, the first element corresponds to bitnum
171              and the second to numbits.  The remainder are uninitialised.
172
173       ·      For  LINCOM  fields, the first GD_MAX_LINCOM elements correspond
174              to the slopes (cm) and the next  GD_MAX_LINCOM  elements  corre‐
175              spond  to the offsets (cb).  Only the first n_fields elements of
176              these  two  sets  are  initialised.   Notably,  this  means  for
177              n_fields  <  GD_MAX_LINCOM, there will be uninitialised elements
178              in the middle of these arrays between the element  corresponding
179              to cm[n_fields - 1] and the element corresponding to cb[0].
180
181       ·      For MPLEX fields, the first element corresponds to count_val and
182              the second to period.  The remainder are uninitialised.
183
184       ·      For PHASE fields, the first element corresponds to  shift.   The
185              remainder are uninitialised.
186
187       ·      For  POLYNOM  fields,  these arrays correspond with the co-effi‐
188              cients ca.  Only the  first  poly_ord  +  1  elements  are  ini‐
189              tialised.
190
191       ·      For  RAW  fields, the first element corresponds to spf.  The re‐
192              mainder are uninitialised.
193
194       ·      For RECIP fields, the first element  corresponds  to  cdividend.
195              The remainder are uninitialised.
196
197       ·      For  WINDOW  fields, the first element corresponds to threshold.
198              The remainder are uninitialised.
199
200       The scalar parameters are NULL if a literal parameter was used, or else
201       a field code specifying the scalar parameters.
202
203       If  an  element  of  scalar specifies a CARRAY field, the corresponding
204       scalar_ind will indicate the element of the  CARRAY  used.   For  CONST
205       fields, scalar_ind will be -1.
206
207
208   BIT and SBIT Members
209       A gd_entry_t describing a BIT or SBIT entry, will also provide:
210
211              typedef struct {
212                ...
213
214                const char *in_fields[1];     /* input field code */
215                int         bitnum;           /* first bit */
216                int         numbits;          /* bit length */
217
218                ...
219              } gd_entry_t;
220
221       The  in_fields  member  is  an array of length one containing the input
222       field code.
223
224       The bitnum member indicates the number of the first bit  (counted  from
225       zero)  extracted  from  the  input.   If  this value was specified as a
226       scalar field code, this will be the numerical value of that field,  and
227       scalar[0]  will contain the field code itself, otherwise scalar[0] will
228       be NULL.
229
230       The numbits member indicates the number of  bits  which  are  extracted
231       from  the  input.   If this value was specified as a scalar field code,
232       this will be the numerical value of that field, and scalar[1] will con‐
233       tain the field code itself, otherwise scalar[1] will be NULL.
234
235
236   CARRAY Members
237       A gd_entry_t describing a CARRAY entry, will also provide:
238
239              typedef struct {
240                ...
241
242                gd_type_t  const_type; /* data type in format specification */
243                size_t     array_len;  /* length of array data */
244
245                ...
246              } gd_entry_t;
247
248       The  const_type  member  indicates  the data type of the constant value
249       stored in the format file metadata.  See gd_getdata(3) for  a  list  of
250       valid values that a variable of type gd_type_t may take.
251
252       The array_len member gives the number of elements in the array.
253
254
255   CONST Members
256       A gd_entry_t describing a CONST entry, will also provide:
257
258              typedef struct {
259                ...
260
261                gd_type_t  const_type; /* data type in format specification */
262
263                ...
264              } gd_entry_t;
265
266       The  const_type  member  indicates  the data type of the constant value
267       stored in the format file metadata.  See gd_getdata(3) for  a  list  of
268       valid values that a variable of type gd_type_t may take.
269
270
271   DIVIDE, INDIR, MULTIPLY, and SINDIR Members
272       A  gd_entry_t  describing  a  DIVIDE, INDIR, MULTIPLY, or SINDIR entry,
273       will also provide:
274
275              typedef struct {
276                ...
277
278                const char *in_fields[2];     /* input field codes */
279
280                ...
281              } gd_entry_t;
282
283       The in_fields member is an array of length  two  containing  the  input
284       field codes.
285
286
287   INDEX Members
288       A  gd_entry_t describing an INDEX entry, which is used only for the im‐
289       plicit INDEX field, provides no additional data.
290
291
292   LINCOM Members
293       A gd_entry_t describing a LINCOM entry, will also provide:
294
295              typedef struct {
296                ...
297
298                int            n_fields;                 /* # of inputs */
299                const char    *in_fields[GD_MAX_LINCOM]; /* input fields(s) */
300                double complex cm[GD_MAX_LINCOM];        /* scale factor(s) */
301                double         m[GD_MAX_LINCOM];         /* scale factor(s) */
302                double complex cb[GD_MAX_LINCOM];        /* offset terms(s) */
303                double         b[GD_MAX_LINCOM];         /* offset terms(s) */
304
305                ...
306              } gd_entry_t;
307
308       The n_fields member indicates the number of input fields.  It  will  be
309       between  one  and GD_MAX_LINCOM inclusive.  GD_MAX_LINCOM is defined in
310       getdata.h as the maximum number of input fields permitted by a LINCOM.
311
312       The in_fields member is an array of length GD_MAX_LINCOM containing the
313       input  field  code(s).   Only the first n_fields elements of this array
314       are initialised.  The remaining elements contain uninitialised data.
315
316       The cm and cb members are arrays of  the  scale  factor(s)  and  offset
317       term(s)  for the LINCOM.  Only the first n_fields elements of these ar‐
318       ray contain meaningful data.  If any of these values were specified  as
319       a  scalar  field  code, this will be the numerical value of that field.
320       The field code corresponding to cm[i] will be stored in  scalar[i]  and
321       the  field  code  associated  with  cb[i]  will be stored in scalar[i +
322       GD_MAX_LINCOM].  Otherwise the  corresponding  scalar  member  will  be
323       NULL.   See NOTES below on changes to the declaration of cm and cb when
324       using the C89 GetData API.
325
326       The elements of m and b are the real parts of  the  corresponding  ele‐
327       ments of cm and cb.
328
329
330   LINTERP Members
331       A gd_entry_t describing a LINTERP entry, will also provide:
332
333              typedef struct {
334                ...
335
336                const char *table             /* linterp table filename */
337                const char *in_fields[1];     /* input field code */
338
339                ...
340              } gd_entry_t;
341
342       The  table  member  is the pathname to the look up table on disk.  This
343       the path as it appars in the format specification.  It may  be  a  path
344       relative  to  the  fragment  directory.  For an canonicalised, absolute
345       version of this path, see gd_linterp_tablename(3).
346
347       The in_fields member is an array of length  one  containing  the  input
348       field code.
349
350
351   MPLEX Members
352       A gd_entry_t describing a MPLEX entry, will also provide:
353
354              typedef struct {
355                ...
356
357                const char *in_fields[2];   /* input field codes */
358                int         count_val;      /* value of the multiplex index */
359                int         period;         /* samples between successive
360                                                                    indices */
361
362                ...
363              } gd_entry_t;
364
365       The  in_fields member contains the field codes of the input field (ele‐
366       ment 0) and the multiplex index field (element 1).
367
368       The count_val member is the value of the multiplex index field when the
369       output field is stored in the input field.
370
371       The  period  member  is the number of samples between successive occur‐
372       rances of count_val in the index vector, or zero, if this is not  known
373       or constant.  This is only used to determine how far to look back for a
374       starting value for the output field; see gd_mplex_lookback(3).
375
376
377   PHASE Members
378       A gd_entry_t describing a PHASE entry, will also provide:
379
380              typedef struct {
381                ...
382
383                const char *in_fields[1];     /* input field code */
384                gd_int64_t  shift;            /* phase shift */
385
386                ...
387              } gd_entry_t;
388
389       The in_fields member is an array of length  one  containing  the  input
390       field code.
391
392       The  shift  member indicates the shift in samples.  The gd_int64_t type
393       is a 64-bit signed integer type.  A positive value  indicates  a  shift
394       forward  in  time  (towards  larger  frame numbers).  If this value was
395       specified as a scalar field code, this will be the numerical  value  of
396       that field, and scalar[0] will contain the field code itself, otherwise
397       scalar[0] will be NULL.
398
399
400   POLYNOM Members
401       A gd_entry_t describing a POLYNOM entry, will also provide:
402
403              typedef struct {
404                ...
405
406                int            poly_ord;                /* polynomial order */
407                const char    *in_fields[1];            /* input field(s) */
408                double complex ca[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */
409                double         a[GD_MAX_POLY_ORD + 1];  /* co-efficients(s) */
410
411                ...
412              } gd_entry_t;
413
414       The poly_ord member indicates the order of the polynomial.  It will  be
415       between  one and GD_MAX_POLY_ORD inclusive.  GD_MAX_POLY_ORD is defined
416       in getdata.h as the maximum order of polynomial permitted by a POLYNOM.
417
418       The in_fields member is an array of length  one  containing  the  input
419       field code.
420
421       The ca members are arrays of the co-efficient(s) for the POLYNOM.  Only
422       the first poly_ord + 1 elements of this array contains meaningful data.
423       If any of these values were specified as a scalar field code, this will
424       be the numerical value of that field.  The field code corresponding  to
425       ca[i]  will be stored in scalar[i].  Otherwise the corresponding scalar
426       member will be NULL.  See NOTES below on changes to the declaration  of
427       ca when using the C89 GetData API.
428
429       The  elements  of a are the real parts of the corresponding elements of
430       ca.
431
432
433   RAW Members
434       A gd_entry_t describing a RAW entry, will also provide:
435
436              typedef struct {
437                ...
438
439                unsigned int  spf;          /* samples per frame on disk */
440                gd_type_t     data_type;    /* data type on disk */
441
442                ...
443              } gd_entry_t;
444
445       The spf member contains the samples per frame of  the  binary  data  on
446       disk.  If this value was specified as a scalar field code, this will be
447       the numerical value of that field, and scalar[0] will contain the field
448       code itself, otherwise scalar[0] will be NULL.
449
450       The  data_type  member  indicates  the  data type of the binary data on
451       disk.  See gd_getdata(3) for a list of valid values that a variable  of
452       type gd_type_t may take.
453
454
455   RECIP Members
456       A gd_entry_t describing a RECIP entry, will also provide:
457
458              typedef struct {
459                ...
460
461                const char    *in_fields[1];         /* input field code */
462                double complex cdividend;            /* scalar dividend */
463                double         dividend;             /* scalar dividend */
464
465                ...
466              } gd_entry_t;
467
468       The  in_fields  member  is  an array of length one containing the input
469       field code.
470
471       The cdividend member provides the constant dividend of the computed di‐
472       vision.   If this value was specified as a scalar field code, this will
473       be the numerical value of that field, and scalar[0]  will  contain  the
474       field code itself, otherwise scalar[0] will be NULL.  The dividend mem‐
475       ber contains the real part of cdividend.
476
477
478   STRING Members
479       A gd_entry_t describing a STRING entry provides no additional data.
480
481
482   WINDOW Members
483       A gd_entry_t describing a WINDOW entry, will also provide:
484
485              typedef struct {
486                ...
487
488                const char    *in_fields[2];  /* input field codes */
489                gd_windop_t   windop;         /* comparison operator */
490                gd_triplet_t  threshold;      /* the value compared against */
491
492                ...
493              } gd_entry_t;
494
495       The in_fields member contains the field codes of the input field  (ele‐
496       ment 0) and the check field (element 1).
497
498       The  windop  member equals one of the following symbols, indicating the
499       particular comparison performed on the check field:
500
501       GD_WINDOP_EQ
502               data are extracted when the check field equals threshold;
503
504       GD_WINDOP_GE
505               data are extracted when the check  field  is  greater  than  or
506               equal to threshold;
507
508       GD_WINDOP_GT
509               data  are  extracted  when  the check field is strictly greater
510               than threshold;
511
512       GD_WINDOP_LE
513               data are extracted when the check field is less than  or  equal
514               to threshold;
515
516       GD_WINDOP_LT
517               data  are  extracted when the check field is strictly less than
518               threshold;
519
520       GD_WINDOP_NE
521               data are extracted  when  the  check  field  is  not  equal  to
522               threshold;
523
524       GD_WINDOP_SET
525               data  are  extracted when at least one bit in threshold is also
526               set in the check field;
527
528       GD_WINDOP_CLR
529               data are extracted when at least one bit in  threshold  is  not
530               set in the check field.
531
532       The  threshold  is the value against which the check field is compared.
533       The gd_triplet_t type is defined as:
534
535              typedef union {
536                gd_int64_t i;
537                gd_uint64_t u;
538                double r;
539              } gd_triplet_t;
540
541       The particular element of the union to use  depends  on  the  value  of
542       windop:
543
544       ·      For  GD_WINDOP_EQ  and GD_WINDOP_NE, the signed integer element,
545              threshold.i, is set;
546
547       ·      For GD_WINDOP_SET and GD_WINDOP_CLR, the unsigned  integer  ele‐
548              ment, threshold.u, is set;
549
550       ·      For  all  other  values  of  windop, the floating point element,
551              threshold.r, is set.
552
553

NOTES

555       When using the C89 GetData API (by defining GD_C89_API before including
556       getdata.h), the data types and names of several of the entry parameters
557       are different.  The following table lists the  correspondences  between
558       members in the C99 and C89 APIs.
559
560
561                    C99 API                           C89 API
562                     int   bitnum                int   u.bit.bitnum
563                     int   numbits               int   u.bit.numbits
564                     int   n_fields              int   u.lincom.n_fields
565          double complex   cm[]               double   u.lincom.cm[][2]
566                  double   m[]                double   u.lincom.m[]
567          double complex   cb[]               double   u.lincom.cb[][2]
568                  double   b[]                double   u.lincom.b[]
569             const char*   table         const char*   u.linterp.table
570                     int   count_val             int   u.mplex.count_val
571                     int   period                int   u.mplex.period
572              gd_int64_t   shift          gd_int64_t   u.phase.shift
573                     int   poly_ord              int   u.polynom.poly_ord
574          double complex   ca[]               double   u.polynom.ca[][2]
575                  double   a[]                double   u.polynom.a[]
576            unsigned int   spf          unsigned int   u.raw.spf
577               gd_type_t   data_type       gd_type_t   u.raw.data_type
578          double complex   cdividend          double   u.recip.cdividend[2]
579                  double   dividend           double   u.recip.dividend
580               gd_type_t   const_type      gd_type_t   u.scalar.const_type
581                  size_t   array_len          size_t   u.scalar.array_len
582             gd_windop_t   windop        gd_windop_t   u.window.windop
583            gd_triplet_t   threshold    gd_triplet_t   u.window.threshold
584
585       In the case of complex valued data in the C89 API, the first element of
586       the two-element array is the real part of the complex number,  and  the
587       second element is the imaginary part.
588
589

HISTORY

591       The get_entry() function appeared in GetData-0.3.0.
592
593       In GetData-0.7.0, this function was renamed to gd_entry().
594
595       In  GetData-0.10.0,  the error return from these functions changed from
596       -1 to a negative-valued error code.
597
598
599   Changes to the gd_entry_t structure
600       Field-type specific members have been added to the structure as support
601       for those field types have been introduced to the library:
602
603       ·      BIT, LINCOM, LINTERP, MULTIPLY, PHASE, and RAW were supported in
604              GetData-0.3.0 (Dirfile Standards Version 5).
605
606       ·      CONST  and  STRING  entries  were  introduced  in  GetData-0.4.0
607              (Dirfile  Standards  Version  6); this is also the first version
608              that treats INDEX as a normal field.  In earlier versions,  try‐
609              ing to retrieve the metadata for the INDEX field would fail.
610
611       ·      POLYNOM  and  SBIT  entries  were  introduced  in  GetData-0.6.0
612              (Dirfile Standards Version 7).
613
614       ·      CARRAY, DIVIDE, and RECIP  entries  were  introduced  in  GetDa‐
615              ta-0.7.0 (Dirfile Standards Version 8).
616
617       ·      MPLEX  and  WINDOW  entries  were  introduced  in  GetData-0.8.0
618              (Dirfile Standards Version 9).
619
620       ·      INDIR, SARRAY, and SINDIR  entries  were  introduced  in  GetDa‐
621              ta-0.10.0 (Dirfile Standards Version 10).
622
623       The  scalar member appeared in GetData-0.6.0.  This release also intro‐
624       duced the complex-valued scalar members (cm, cb, &c.)
625
626       The scalar_ind member appeared in GetData-0.7.0.   This  was  also  the
627       first  release with a working ANSI C (C89) conforming alternate defini‐
628       tion.
629
630       Before Getdata-0.8.4, the  period  member  for  MPLEX  data  was  named
631       count_max.
632
633       Before GetData-0.9.0, the flags member is missing.  In it's place was:
634
635              int comp_scal;     /* Scalar parameters are complex-valued */
636
637       which  was non-zero to indicate complex-valued parameters, which is now
638       indicated by the GD_EN_COMPSCAL flag.
639
640

SEE ALSO

642       dirfile(5),     gd_alloc_funcs(3),      gd_cbopen(3),      gd_error(3),
643       gd_error_string(3),        gd_field_list(3),        gd_fragmentname(3),
644       gd_free_entry_strings(3), gd_linterp_tablename(3) gd_mplex_lookback(3),
645       gd_raw_filename(3), gd_validate(3)
646
647
648
649Version 0.10.0                 25 December 2016                    gd_entry(3)
Impressum