table of contents
other versions
- wheezy 0.7.3-6
- jessie 0.7.3-6+b2
- testing 0.9.4-1
- unstable 0.9.4-1
- experimental 0.10.0-1
gd_getdata(3) | GETDATA | gd_getdata(3) |
NAME¶
gd_getdata — retrieve data from a dirfile databaseSYNOPSIS¶
#include <getdata.h>size_t
gd_getdata(DIRFILE *dirfile, const char
*field_code, off_t first_frame, off_t
first_sample, size_t num_frames, size_t
num_samples, gd_type_t return_type, void
*data_out);
DESCRIPTION¶
The gd_getdata() function queries a dirfile(5) database specified by dirfile for the field field_code. It fetches num_frames frames plus num_samples samples from this field, starting first_sample samples past frame first_frame. The data is converted to the data type specified by return_type, and stored in the user-supplied buffer data_out.first_frame * samples_per_frame
+ first_sample
as measured from the start of the dirfile, where samples_per_frame is the
number of samples per frame as returned by gd_spf(3). The number of
samples fetched is, similarly,
num_frames * samples_per_frame +
num_samples.
Although calling gd_getdata() using both samples and frames is possible,
the function is typically called with either num_samples and
first_sample, or num_frames and first_frames, equal to
zero.
- GD_UINT8
- unsigned 8-bit integer
- GD_INT8
- signed (two's complement) 8-bit integer
- GD_UINT16
- unsigned 16-bit integer
- GD_INT16
- signed (two's complement) 16-bit integer
- GD_UINT32
- unsigned 32-bit integer
- GD_INT32
- signed (two's complement) 32-bit integer
- GD_UINT64
- unsigned 64-bit integer
- GD_INT64
- signed (two's complement) 64-bit integer
- GD_FLOAT32
- IEEE-754 standard 32-bit single precision floating point number
- GD_FLOAT64
- IEEE-754 standard 64-bit double precision floating point number
- GD_COMPLEX64
- C99-conformant 64-bit single precision complex number
- GD_COMPLEX128
- C99-conformant 128-bit double precision complex number
- GD_NULL
- the null type: the database is queried as usual, but no data is returned. In this case, data_out is ignored and may be NULL.
RETURN VALUE¶
In all cases, gd_getdata() returns the number of samples (not bytes) successfully read from the database. If the end-of-field is encountered before the requested number of samples have been read, a short count will result. The library does not consider this an error. Requests for data before the beginning-of-field marker, which may have been shifted from frame zero by the presence of a FRAMEOFFSET directive, will result in the the data being padded at the front by NaN or zero depending on whether the return type is of floating point or integral type.- GD_E_ALLOC
- The library was unable to allocate memory.
- GD_E_BAD_CODE
- The field specified by field_code, or one of the fields it uses for input, was not found in the database.
- GD_E_BAD_DIRFILE
- An invalid dirfile was supplied.
- GD_E_BAD_FIELD_TYPE
- The supplied field_code referred to a CONST, CARRAY, or STRING field. The caller should use gd_get_constant(3), gd_get_carray(3), or gd_get_string(3) instead.
- GD_E_BAD_REPR
- The representation suffix specified in field_code, or in one of the field codes it uses for input, was invalid.
- GD_E_BAD_SCALAR
- A scalar field used in the definition of the field was not found, or was not of scalar type.
- GD_E_BAD_TYPE
- An invalid return_type was specified.
- GD_E_DIMENSION
- A scalar field was found where a vector field was expected.
- GD_E_INTERNAL_ERROR
- An internal error occurred in the library while trying to perform the task. This indicates a bug in the library. Please report the incident to the maintainer.
- GD_E_OPEN_LINFILE
- An error occurred while trying to read a LINTERP table from disk.
- GD_E_RAW_IO
- An error occurred while trying to open or read from a file on disk containing a raw field.
- GD_E_RECURSE_LEVEL
- Too many levels of recursion were encountered while trying to resolve field_code. This usually indicates a circular dependency in field specification in the dirfile.
- GD_E_UNKNOWN_ENCODING
- The encoding scheme of a RAW field could not be determined. This may also indicate that the binary file associated with the RAW field could not be found.
- GD_E_UNSUPPORTED
- Reading from dirfiles with the encoding scheme of the specified dirfile is not supported by the library. See dirfile-encoding(5) for details on dirfile encoding schemes.
LIMITATIONS¶
The PHASE field type is poorly defined, since a forward-shifted PHASE field will always encounter the end-of-field marker before its input field does. This has ramifications when using gd_getdata() with streaming data. The Dirfile Standards make tacit admission to this problem by indicating the results of reading a PHASE field beyond the beginning- or end-of-field is "implementation dependent" (see dirfile-format(5)). As with any other field, gd_getdata() will return a short count whenever a read from a PHASE field encounters the end-of-field marker.SEE ALSO¶
dirfile(5), dirfile-encoding(5), gd_open(3), gd_get_constant(3), gd_error(3), gd_error_string(3), gd_nframes(3), gd_spf(3), gd_get_string(3), gd_putdata(3)3 November 2010 | Version 0.7.0 |