Provided by: libgetdata-dev_0.7.3-6_i386 bug

NAME

       gd_getdata -- retrieve data from a dirfile database

SYNOPSIS

       #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.

       The field_code may contain one of the representation suffixes listed in
       dirfile-format(5).   If  it  does,  gd_getdata()   will   compute   the
       appropriate complex norm before returning the data.

       The  dirfile  argument  must point to a valid DIRFILE object previously
       created by a call to gd_open(3).  The argument data_out must point to a
       valid memory location of sufficient size to hold all data requested.

       The first sample returned will be
              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.

       The  return_type argument should be one of the following symbols, which
       indicates the desired return type of the data:

              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.

       The  return  type  of  the data need not be the same as the type of the
       data stored in the database.  Type  conversion  will  be  performed  as
       necessary  to  return  the  requested type.  If the field_code does not
       indicate a representation, but conversion from a  complex  value  to  a
       purely  real  one  is  required, only the real portion of the requested
       vector will be returned.

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.

       If an error has occurred, zero is returned and the dirfile  error  will
       be set to a non-zero value.  Possible error values are:

       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.

       The   dirfile  error  may  be  retrieved  by  calling  gd_error(3).   A
       descriptive error string for the last error encountered can be obtained
       from a call to gd_error_string(3).

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.

       Backward-shifted  PHASE  fields  do not suffer from this problem, since
       gd_getdata() pads reads past the beginning-of-field marker with NaN  or
       zero as appropriate.  Database creators who wish to use the PHASE field
       type with streaming data are encouraged to work around this  limitation
       by only using backward-shifted PHASE fields, by writing RAW data at the
       maximal time lag, and then back-shifting all  data  which  should  have
       been  written  earlier.   Another  possible  work-around  is  to  write
       systematically less data to the first RAW field in  proportion  to  the
       maximal  forward  phase shift.  This method will work with applications
       which respect the database size reported by gd_nframes(3) resulting  in
       these  applications  effectively  ignoring  all  frames  past the frame
       containing the maximally  forward-shifted  PHASE  field's  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)