1gd_entry(3) GETDATA gd_entry(3)
10
14 gd_entry — retrieve a Dirfile field's metadata
15
18 #include <getdata.h>
19 int gd_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t
21 *entry);
22
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 The dirfile argument must point to a valid DIRFILE object previously
31 created by a call to gd_open(3).
32 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 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 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 The returned entry structure, including strings and their pointers may
54 be freely modified by the caller.
55
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 GD_E_ALLOC
64 The library was unable to allocate memory.
65 GD_E_BAD_CODE
67 The field specified by field_code was not found in the data‐
68 base.
69 GD_E_BAD_DIRFILE
71 The supplied dirfile was invalid.
72 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
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 typedef struct {
84 ...
85 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 ...
92 } gd_entry_t;
93 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 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 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 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 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 The flags member is a bitwise or'd collection of the following entry
120 flags:
121 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 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 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 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 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 typedef struct {
159 ...
160 const char *scalar[GD_MAX_POLY_ORD + 1]; /* param. fields */
162 int scalar_ind[GD_MAX_POLY_ORD + 1];
163 /* CARRAY indices */
164 ...
166 } gd_entry_t;
167 Only certain elements of these arrays will be initialised:
169 · For BIT and SBIT fields, the first element corresponds to bitnum
171 and the second to numbits. The remainder are uninitialised.
172 · 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 · For MPLEX fields, the first element corresponds to count_val and
182 the second to period. The remainder are uninitialised.
183 · For PHASE fields, the first element corresponds to shift. The
185 remainder are uninitialised.
186 · 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 · For RAW fields, the first element corresponds to spf. The re‐
192 mainder are uninitialised.
193 · For RECIP fields, the first element corresponds to cdividend.
195 The remainder are uninitialised.
196 · For WINDOW fields, the first element corresponds to threshold.
198 The remainder are uninitialised.
199 The scalar parameters are NULL if a literal parameter was used, or else
201 a field code specifying the scalar parameters.
202 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 BIT and SBIT Members
209 A gd_entry_t describing a BIT or SBIT entry, will also provide:
210 typedef struct {
212 ...
213 const char *in_fields[1]; /* input field code */
215 int bitnum; /* first bit */
216 int numbits; /* bit length */
217 ...
219 } gd_entry_t;
220 The in_fields member is an array of length one containing the input
222 field code.
223 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 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 CARRAY Members
237 A gd_entry_t describing a CARRAY entry, will also provide:
238 typedef struct {
240 ...
241 gd_type_t const_type; /* data type in format specification */
243 size_t array_len; /* length of array data */
244 ...
246 } gd_entry_t;
247 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 The array_len member gives the number of elements in the array.
253 CONST Members
256 A gd_entry_t describing a CONST entry, will also provide:
257 typedef struct {
259 ...
260 gd_type_t const_type; /* data type in format specification */
262 ...
264 } gd_entry_t;
265 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 DIVIDE, INDIR, MULTIPLY, and SINDIR Members
272 A gd_entry_t describing a DIVIDE, INDIR, MULTIPLY, or SINDIR entry,
273 will also provide:
274 typedef struct {
276 ...
277 const char *in_fields[2]; /* input field codes */
279 ...
281 } gd_entry_t;
282 The in_fields member is an array of length two containing the input
284 field codes.
285 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 LINCOM Members
293 A gd_entry_t describing a LINCOM entry, will also provide:
294 typedef struct {
296 ...
297 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 ...
306 } gd_entry_t;
307 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 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 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 The elements of m and b are the real parts of the corresponding ele‐
327 ments of cm and cb.
328 LINTERP Members
331 A gd_entry_t describing a LINTERP entry, will also provide:
332 typedef struct {
334 ...
335 const char *table /* linterp table filename */
337 const char *in_fields[1]; /* input field code */
338 ...
340 } gd_entry_t;
341 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 The in_fields member is an array of length one containing the input
348 field code.
349 MPLEX Members
352 A gd_entry_t describing a MPLEX entry, will also provide:
353 typedef struct {
355 ...
356 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 ...
363 } gd_entry_t;
364 The in_fields member contains the field codes of the input field (ele‐
366 ment 0) and the multiplex index field (element 1).
367 The count_val member is the value of the multiplex index field when the
369 output field is stored in the input field.
370 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 PHASE Members
378 A gd_entry_t describing a PHASE entry, will also provide:
379 typedef struct {
381 ...
382 const char *in_fields[1]; /* input field code */
384 gd_int64_t shift; /* phase shift */
385 ...
387 } gd_entry_t;
388 The in_fields member is an array of length one containing the input
390 field code.
391 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 POLYNOM Members
401 A gd_entry_t describing a POLYNOM entry, will also provide:
402 typedef struct {
404 ...
405 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 ...
412 } gd_entry_t;
413 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 The in_fields member is an array of length one containing the input
419 field code.
420 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 The elements of a are the real parts of the corresponding elements of
430 ca.
431 RAW Members
434 A gd_entry_t describing a RAW entry, will also provide:
435 typedef struct {
437 ...
438 unsigned int spf; /* samples per frame on disk */
440 gd_type_t data_type; /* data type on disk */
441 ...
443 } gd_entry_t;
444 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 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 RECIP Members
456 A gd_entry_t describing a RECIP entry, will also provide:
457 typedef struct {
459 ...
460 const char *in_fields[1]; /* input field code */
462 double complex cdividend; /* scalar dividend */
463 double dividend; /* scalar dividend */
464 ...
466 } gd_entry_t;
467 The in_fields member is an array of length one containing the input
469 field code.
470 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 STRING Members
479 A gd_entry_t describing a STRING entry provides no additional data.
480 WINDOW Members
483 A gd_entry_t describing a WINDOW entry, will also provide:
484 typedef struct {
486 ...
487 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 ...
493 } gd_entry_t;
494 The in_fields member contains the field codes of the input field (ele‐
496 ment 0) and the check field (element 1).
497 The windop member equals one of the following symbols, indicating the
499 particular comparison performed on the check field:
500 GD_WINDOP_EQ
502 data are extracted when the check field equals threshold;
503 GD_WINDOP_GE
505 data are extracted when the check field is greater than or
506 equal to threshold;
507 GD_WINDOP_GT
509 data are extracted when the check field is strictly greater
510 than threshold;
511 GD_WINDOP_LE
513 data are extracted when the check field is less than or equal
514 to threshold;
515 GD_WINDOP_LT
517 data are extracted when the check field is strictly less than
518 threshold;
519 GD_WINDOP_NE
521 data are extracted when the check field is not equal to
522 threshold;
523 GD_WINDOP_SET
525 data are extracted when at least one bit in threshold is also
526 set in the check field;
527 GD_WINDOP_CLR
529 data are extracted when at least one bit in threshold is not
530 set in the check field.
531 The threshold is the value against which the check field is compared.
533 The gd_triplet_t type is defined as:
534 typedef union {
536 gd_int64_t i;
537 gd_uint64_t u;
538 double r;
539 } gd_triplet_t;
540 The particular element of the union to use depends on the value of
542 windop:
543 · For GD_WINDOP_EQ and GD_WINDOP_NE, the signed integer element,
545 threshold.i, is set;
546 · For GD_WINDOP_SET and GD_WINDOP_CLR, the unsigned integer ele‐
548 ment, threshold.u, is set;
549 · For all other values of windop, the floating point element,
551 threshold.r, is set.
552
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 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 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
591 The get_entry() function appeared in GetData-0.3.0.
592 In GetData-0.7.0, this function was renamed to gd_entry().
594 In GetData-0.10.0, the error return from these functions changed from
596 -1 to a negative-valued error code.
597 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 · BIT, LINCOM, LINTERP, MULTIPLY, PHASE, and RAW were supported in
604 GetData-0.3.0 (Dirfile Standards Version 5).
605 · 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 · POLYNOM and SBIT entries were introduced in GetData-0.6.0
612 (Dirfile Standards Version 7).
613 · CARRAY, DIVIDE, and RECIP entries were introduced in GetDa‐
615 ta-0.7.0 (Dirfile Standards Version 8).
616 · MPLEX and WINDOW entries were introduced in GetData-0.8.0
618 (Dirfile Standards Version 9).
619 · INDIR, SARRAY, and SINDIR entries were introduced in GetDa‐
621 ta-0.10.0 (Dirfile Standards Version 10).
622 The scalar member appeared in GetData-0.6.0. This release also intro‐
624 duced the complex-valued scalar members (cm, cb, &c.)
625 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 Before Getdata-0.8.4, the period member for MPLEX data was named
631 count_max.
632 Before GetData-0.9.0, the flags member is missing. In it's place was:
634 int comp_scal; /* Scalar parameters are complex-valued */
636 which was non-zero to indicate complex-valued parameters, which is now
638 indicated by the GD_EN_COMPSCAL flag.
639
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)
646Version 0.10.0 25 December 2016 gd_entry(3)