1
2
3
4
5
6
7
8
9gd_entry(3) GETDATA gd_entry(3)
10
11
12
14 gd_entry — retrieve a Dirfile field's metadata
15
16
18 #include <getdata.h>
19
20 int gd_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t
21 *entry);
22
23
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
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
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
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
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
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)