1get_entry(3) GETDATA get_entry(3)
2
6 get_entry — retrieve a dirfile field's metadata
7
9 #include <getdata.h>
10 int get_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t
12 *entry);
13
15 The get_entry() function queries a dirfile(5) database specified by
16 dirfile and returns the metadata associated with the field specified by
17 field_code. If field_code contains a valid representation suffix, the
18 suffix will be ignored.
19 The dirfile argument must point to a valid DIRFILE object previously
21 created by a call to dirfile_open(3).
22 The entry will be stored in the gd_entry_t structure indicated by the
24 entry argument, which must be allocated by the caller. Members avail‐
25 able in this structure depend on the field type of the field queried.
26 See below for a complete description of this data type.
27 Strings members in entry filled by this function (variously, depending
29 on field type: field, the elements of the in_fields[] array, table; see
30 below) will by dynamically allocated by get_entry() and should not
31 point to allocated memory locations before calling this function. Only
32 strings provided by the gd_entry_t for the particular field type de‐
33 scribed will be allocated. These strings should be deallocated with
34 free(3) by the caller once they are no longer needed. The
35 dirfile_free_entry_strings(3) function is provided as a convenience to
36 do this.
37 The returned entry structure, including strings and their pointers may
39 be freely modified by the caller.
40
43 Upon successful completion, get_entry() returns zero, and writes the
44 field metadata in the supplied gd_entry_t buffer. On error, the sup‐
45 plied gd_entry_t buffer is not modified. In this case, get_entry() re‐
46 turns -1 and sets the dirfile error to a non-zero error value. Possi‐
47 ble error values are:
48 GD_E_BAD_CODE
50 The field specified by field_code was not found in the data‐
51 base.
52 GD_E_BAD_DIRFILE
54 The supplied dirfile was invalid.
55 GD_E_BAD_REPR
57 The representation suffix specified in field_code was not
58 recognised.
59 GD_E_BAD_SCALAR
61 A scalar parameter used in the definition of the field was in‐
62 valid.
63 The dirfile error may be retrieved by calling get_error(3). A descrip‐
65 tive error string for the last error encountered can be obtained from a
66 call to get_error_string(3).
67
69 Members available in the gd_entry_t structure depend on the field type
70 described. All gd_entry_t objects are guaranteed to have at least:
71 typedef struct {
73 ...
74 const char *field; /* field code */
76 gd_entype_t field_type; /* field type */
77 int fragment_index; /* format file fragment index */
78 ...
80 } gd_entry_t;
81 The field member is the field code of the entry (i.e. its string name).
83 If the call to get_entry(3) is successful, this will be the field name
84 specified as part of the field_code argument.
85 The field_type member indicates the field type of the entry. This is
87 an integer type equal to one of the following symbols:
88 GD_BIT_ENTRY, GD_CONST_ENTRY, GD_INDEX_ENTRY,
90 GD_LINCOM_ENTRY, GD_LINTERP_ENTRY, GD_MULTIPLY_ENTRY,
91 GD_PHASE_ENTRY, GD_POLYNOM_ENTRY, GD_RAW_ENTRY, GD_SBIT_ENTRY,
92 GD_STRING_ENTRY.
93 GD_INDEX_ENTRY is a special field type used only for the implicit INDEX
95 field. The meaning of the other symbols should be self-explanatory.
96 The fragment_index member indicates the format file fragment in which
98 this field is defined. This is an integer index to the Dirfile's list
99 of parsed format file fragments. The name of the file corresponding to
100 fragment_index may be obtained by calling get_fragmentname(3). A value
101 of zero for this field indicates that the field is defined in the pri‐
102 mary format file, the file called format in the root dirfile directory
103 (see dirfile(5)).
104 Remaining fields in the gd_entry_t structure depend on the value of
106 field_type. Callers are advised to check field_type before attempting
107 to access the remaining members. Members for different field types may
108 be stored in the same physical location in core. Accordingly, attempt‐
109 ing to access a member not declared for the appropriate field type will
110 have unspecified results.
111 BIT and SBIT Members
114 A gd_entry_t describing a BIT or SBIT entry, will also provide:
115 typedef struct {
117 ...
118 const char *in_fields[1]; /* input field code */
120 const char *scalar[2]; /* parameter field codes */
121 gd_bit_t bitnum; /* first bit */
122 gd_bit_t numbits; /* bit length */
123 ...
125 } gd_entry_t;
126 The in_fields member is an array of length one containing the input
128 field code.
129 The scalar member is an array of length two containing the field codes
131 specifying bitnum and numbits, or NULLs if numeric literal parameters
132 were used.
133 The bitnum member indicates the number of the first bit (counted from
135 zero) extracted from the input. The gd_bit_t type is a signed 16-bit
136 integer type. If this value was specified as a CONST field code, this
137 will be the numerical value of that field, and scalar[0] will contain
138 the field code itself, otherwise scalar[0] will be NULL.
139 The numbits member indicates the number of bits which are extracted
141 from the input. If this value was specified as a CONST field code,
142 this will be the numerical value of that field, and scalar[1] will con‐
143 tain the field code itself, otherwise scalar[1] will be NULL.
144 CONST Members
147 A gd_entry_t describing a CONST entry, will also provide:
148 typedef struct {
150 ...
151 gd_type_t const_type; /* data type in format file */
153 ...
155 } gd_entry_t;
156 The const_type member indicates the data type of the constant value
158 stored in the format file metadata. See getdata(3) for a list of valid
159 values that a variable of type gd_type_t may take.
160 INDEX Members
163 A gd_entry_t describing an INDEX entry, which is used only for the im‐
164 plicit INDEX field, provides no additional data.
165 LINCOM Members
168 A gd_entry_t describing a LINCOM entry, will also provide:
169 typedef struct {
171 ...
172 int n_fields; /* # of input fields */
174 int comp_scal; /* complex scalar flag */
175 const char *in_fields[GD_MAX_LINCOM]; /* input field code(s) */
176 const char *scalar[2 * GD_MAX_LINCOM]; /* param. field codes */
177 double complex cm[GD_MAX_LINCOM]; /* scale factor(s) */
178 double m[GD_MAX_LINCOM]; /* scale factor(s) */
179 double complex cb[GD_MAX_LINCOM]; /* offset terms(s) */
180 double b[GD_MAX_LINCOM]; /* offset terms(s) */
181 ...
183 } gd_entry_t;
184 The n_fields member indicates the number of input fields. It will be
186 between one and GD_MAX_LINCOM inclusive, which is defined in getdata.h
187 to the maximum number of input fields permitted by a LINCOM.
188 The comp_scal member is non-zero if any of the scale factors or offset
190 terms have a non-zero imaginary part. (That is, if comp_scal is zero,
191 the elements of cm and cb equal the corresponding elements of m and b.)
192 members.)
193 The in_fields member is an array of length GD_MAX_LINCOM containing the
195 input field code(s). Only the first n_fields elements of this array
196 are initialised. The remaining elements contain uninitialised data.
197 The scalar member is an array of length twice GD_MAX_LINCOM containing
199 the field codes specifying the slope factors and offset terms for the
200 field, or NULLs if numberical literal parameters were used. The first
201 GD_MAX_LINCOM array elements contain the scale factors. The remaining
202 GD_MAX_LINCOM array elements contain the offset terms. Array elements
203 scalar[i] and scalar[i + GD_MAX_LINCOM], for i >= n_fields, contain
204 uninitialised data.
205 The cm and cb members are arrays of the scale factor(s) and offset
207 term(s) for the LINCOM. Only the first n_fields elements of these ar‐
208 ray contain meaningful data. If any of these values were specified as
209 a CONST field code, this will be the numerical value of that field.
210 The field code corresponding to cm[i] will be stored in scalar[i] and
211 the field code associated with cb[i] will be stored in scalar[i +
212 GD_MAX_LINCOM]. Otherwise the corresponding scalar member will be
213 NULL. See NOTES below on changes to the declaration of cm and cb when
214 using the C89 GetData API.
215 The elements of m and b are the real parts of the corresponding ele‐
217 ments of cm and cb.
218 LINTERP Members
221 A gd_entry_t describing a LINTERP entry, will also provide:
222 typedef struct {
224 ...
225 const char *table /* linterp table filename */
227 const char *in_fields[1]; /* input field code */
228 ...
230 } gd_entry_t;
231 The table member is the pathname to the look up table on disk.
233 The in_fields member is an array of length one containing the input
235 field code.
236 MULTIPLY Members
239 A gd_entry_t describing a MULTIPLY entry, will also provide:
240 typedef struct {
242 ...
243 const char *in_fields[2]; /* input field codes */
245 ...
247 } gd_entry_t;
248 The in_fields member is an array of length two containing the input
250 field codes.
251 PHASE Members
254 A gd_entry_t describing a PHASE entry, will also provide:
255 typedef struct {
257 ...
258 const char *in_fields[1]; /* input field code */
260 const char *scalar[1]; /* parameter field codes */
261 gd_shift_t shift; /* phase shift */
262 ...
264 } gd_entry_t;
265 The in_fields member is an array of length one containing the input
267 field code.
268 The scalar member is an array of length one containing the field code
270 specifying shift, or NULL if a numeric literal parameter was used.
271 The shift member indicates the shift in samples. The gd_shift_t type
273 is a 64-bit signed integer type. A positive value indicates a shift
274 forward in time (towards larger frame numbers). If this value was
275 specified as a CONST field code, this will be the numerical value of
276 that field, and scalar[0] will contain the field code itself, otherwise
277 scalar[0] will be NULL.
278 POLYNOM Members
281 A gd_entry_t describing a POLYNOM entry, will also provide:
282 typedef struct {
284 ...
285 int poly_ord; /* polynomial order */
287 int comp_scal; /* complex scalar flag */
288 const char *in_fields[1]; /* input field code(s) */
289 const char *scalar[GD_MAX_POLY_ORD + 1];
290 /* co-eff. field codes */
291 double complex ca[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */
292 double a[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */
293 ...
295 } gd_entry_t;
296 The poly_ord member indicates the order of the polynomial. It will be
298 between one and GD_MAX_POLY_ORD inclusive, which is defined in getda‐
299 ta.h to the maximum order of polynomial permitted by a POLYNOM.
300 The comp_scal member is non-zero if any of the co-efficients have a
302 non-zero imaginary part. (That is, if comp_scal is zero, the elements
303 of ca equal the corresponding elements of a.)
304 The in_fields member is an array of length one containing the input
306 field code.
307 The scalar member is an array of length one more than GD_MAX_POLYORD
309 containing the field codes specifying the co-efficients for the field,
310 or NULLs if numberical literal parameters were used. Only the first
311 poly_ord + 1 elements are initialised. The remaining elements contain
312 uninitialised data.
313 The ca members are arrays of the co-efficient(s) for the POLYNOM. Only
315 the first poly_ord + 1 elements of this array contains meaningful data.
316 If any of these values were specified as a CONST field code, this will
317 be the numerical value of that field. The field code corresponding to
318 ca[i] will be stored in scalar[i]. Otherwise the corresponding scalar
319 member will be NULL. See NOTES below on changes to the declaration of
320 ca when using the C89 GetData API.
321 The elements of a are the real parts of the corresponding elements of
323 ca.
324 RAW Members
327 A gd_entry_t describing a RAW entry, will also provide:
328 typedef struct {
330 ...
331 const char *scalar[1]; /* parameter field codes */
333 gd_spf_t spf; /* samples per frame on disk */
334 gd_type_t data_type; /* data type on disk */
335 ...
337 } gd_entry_t;
338 The scalar member is an array of length one containing the field code
340 specifying spf, or NULL if a numeric literal parameter was used.
341 The spf member contains the samples per frame of the binary data on
343 disk. The gd_spf_t type is an unsigned 16-bit integer type. If this
344 value was specified as a CONST field code, this will be the numerical
345 value of that field, and scalar[0] will contain the field code itself,
346 otherwise scalar[0] will be NULL.
347 The data_type member indicates the data type of the binary data on
349 disk. See getdata(3) for a list of valid values that a variable of
350 type gd_type_t may take.
351 STRING Members
354 A gd_entry_t describing a STRING entry provides no additional data.
355
358 When using the C89 GetData API (by defining GETDATA_C89_API before in‐
359 cluding getdata.h), the complex valued array members of gd_entry_t used
360 in the specification of LINCOM and POLYNOM entries will be replaced by
361 purely real arrays. These will have the prototypes such as:
362 double cm[GD_MAX_LINCOM][2];
364 double cb[GD_MAX_LINCOM][2];
365 double ca[GD_MAX_POLY_ORD + 1][2];
366 The first element of the two element array is the real part of the com‐
368 plex number, and the second element is the imaginary part.
369
372 dirfile(5), dirfile_free_entry_strings(3), dirfile_open(3), getdata(3),
373 get_error(3), get_error_string(3), get_field_list(3), get_fragment‐
374 name(3), get_raw_filename(3)
375Version 0.6.0 2 November 2009 get_entry(3)