1getdata(3) GETDATA getdata(3)
2
6 getdata — retrieve data from a dirfile database
7
9 #include <getdata.h>
10 size_t getdata(DIRFILE *dirfile, const char *field_code, off_t
12 first_frame, off_t first_sample, size_t num_frames, size_t
13 num_samples, gd_type_t return_type, void *data_out);
14
16 The getdata() function queries a dirfile(5) database specified by
17 dirfile for the field field_code. It fetches num_frames frames plus
18 num_samples samples from this field, starting first_sample samples past
19 frame first_frame. The data is converted to the data type specified by
20 return_type, and stored in the user-supplied buffer data_out.
21 The field_code may contain one of the representation suffixes listed in
23 dirfile-format(5). If it does, getdata will compute the appropriate
24 complex norm before returning the data.
25 The dirfile argument must point to a valid DIRFILE object previously
27 created by a call to dirfile_open(3). The argument data_out must point
28 to a valid memory location of sufficient size to hold all data request‐
29 ed.
30 The first sample returned will be
32 first_frame * samples_per_frame + first_sample
33 as measured from the start of the dirfile, where samples_per_frame is
34 the number of samples per frame as returned by get_spf(3). The number
35 of samples fetched is, similarly,
36 num_frames * samples_per_frame + num_samples.
37 Although calling getdata() using both samples and frames is possible,
38 the function is typically called with either num_samples and first_sam‐
39 ple, or num_frames and first_frames, equal to zero.
40 The return_type argument should be one of the following symbols, which
42 indicates the desired return type of the data:
43 GD_UINT8 unsigned 8-bit integer
45 GD_INT8 signed (two's complement) 8-bit integer
47 GD_UINT16 unsigned 16-bit integer
49 GD_INT16 signed (two's complement) 16-bit integer
51 GD_UINT32 unsigned 32-bit integer
53 GD_INT32 signed (two's complement) 32-bit integer
55 GD_UINT64 unsigned 64-bit integer
57 GD_INT64 signed (two's complement) 64-bit integer
59 GD_FLOAT32 IEEE-754 standard 32-bit single precision floating
61 point number
62 GD_FLOAT64 IEEE-754 standard 64-bit double precision floating
64 point number
65 GD_COMPLEX64
67 C99-conformant 64-bit single precision complex number
68 GD_COMPLEX128
70 C99-conformant 128-bit double precision complex num‐
71 ber
72 GD_NULL the null type: the database is queried as usual, but
74 no data is returned. In this case, data_out is ig‐
75 nored and may be NULL.
76 The return type of the data need not be the same as the type of the da‐
78 ta stored in the database. Type conversion will be performed as neces‐
79 sary to return the requested type. If the field_code does not indicate
80 a representation, but conversion from a complex value to a purely real
81 one is required, only the real portion of the requested vector will be
82 returned.
83
86 In all cases, getdata() returns the number of samples (not bytes) suc‐
87 cessfully read from the database. If the end-of-field is encountered
88 before the requested number of samples have been read, a short count
89 will result. The library does not consider this an error. Requests
90 for data before the beginning-of-field marker, which may have been
91 shifted from frame zero by the presence of a FRAMEOFFSET directive,
92 will result in the the data being padded at the front by NaN or zero
93 depending on whether the return type is of floating point or integral
94 type.
95 If an error has occurred, zero is returned and the dirfile error will
97 be set to a non-zero value. Possible error values are:
98 GD_E_ALLOC
100 The library was unable to allocate memory.
101 GD_E_BAD_CODE
103 The field specified by field_code, or one of the fields it uses
104 for input, was not found in the database.
105 GD_E_BAD_DIRFILE
107 An invalid dirfile was supplied.
108 GD_E_BAD_FIELD_TYPE
110 The supplied field_code referred to a CONST or STRING field.
111 The caller should use get_constant(3), or get_string(3) in‐
112 stead.
113 GD_E_BAD_REPR
115 The representation suffix specified in field_code, or in one of
116 the field codes it uses for input, was invalid.
117 GD_E_BAD_SCALAR
119 A scalar field used in the definition of the field was not
120 found, or was not of scalar type.
121 GD_E_BAD_TYPE
123 An invalid return_type was specified.
124 GD_E_DIMENSION
126 A scalar field was found where a vector field was expected.
127 GD_E_INTERNAL_ERROR
129 An internal error occurred in the library while trying to per‐
130 form the task. This indicates a bug in the library. Please
131 report the incident to the maintainer.
132 GD_E_OPEN_LINFILE
134 An error occurred while trying to read a LINTERP table from
135 disk.
136 GD_E_RAW_IO
138 An error occurred while trying to open or read from a file on
139 disk containing a raw field.
140 GD_E_RECURSE_LEVEL
142 Too many levels of recursion were encountered while trying to
143 resolve field_code. This usually indicates a circular depen‐
144 dency in field specification in the dirfile.
145 GD_E_UNKNOWN_ENCODING
147 The encoding scheme of a RAW field could not be determined.
148 This may also indicate that the binary file associated with the
149 RAW field could not be found.
150 GD_E_UNSUPPORTED
152 Reading from dirfiles with the encoding scheme of the specified
153 dirfile is not supported by the library. See dirfile-encod‐
154 ing(5) for details on dirfile encoding schemes.
155 The dirfile error may be retrieved by calling get_error(3). A descrip‐
157 tive error string for the last error encountered can be obtained from a
158 call to get_error_string(3).
159
161 The PHASE field type is poorly defined, since a forward-shifted PHASE
162 field will always encounter the end-of-field marker before its input
163 field does. This has ramifications when using getdata() with streaming
164 data. The Dirfile Standards make tacit admission to this problem by
165 indicating the results of reading a PHASE field beyond the beginning-
166 or end-of-field is "implementation dependent" (see dirfile-format(5)).
167 As with any other field, getdata() will return a short count whenever a
168 read from a PHASE field encounters the end-of-field marker.
169 Backward-shifted PHASE fields do not suffer from this problem, since
171 getdata() pads reads past the beginning-of-field marker with NaN or ze‐
172 ro as appropriate. Database creators who wish to use the PHASE field
173 type with streaming data are encouraged to work around this limitation
174 by only using backward-shifted PHASE fields, by writing RAW data at the
175 maximal time lag, and then back-shifting all data which should have
176 been written earlier. Another possible work-around is to write system‐
177 atically less data to the first RAW field in proportion to the maximal
178 forward phase shift. This method will work with applications which re‐
179 spect the database size reported by get_nframes(3) resulting in these
180 applications effectively ignoring all frames past the frame containing
181 the maximally forward-shifted PHASE field's end-of-field marker.
182
185 dirfile(5), dirfile-encoding(5), dirfile_open(3), get_constant(3),
186 get_error(3), get_error_string(3), get_nframes(3), get_spf(3),
187 get_string(3), putdata(3)
188Version 0.6.1 9 February 2010 getdata(3)