NAME

       gd_bof — find the start of data in a Dirfile field

SYNOPSIS

       #include <getdata.h>

       off_t gd_bof(DIRFILE *dirfile, const char *field_code);

DESCRIPTION

       The  gd_bof()  function  queries  a dirfile(5) database specified by dirfile and finds the
       beginning-of-field marker for the vector field given by field_code.

       The caller should not assume that the beginning-of-field marker falls on a frame boundary.
       The beginning-of-field marker is never negative.

       For a RAW field, the beginning-of-field corresponds to the frame offset of that field (see
       gd_frameoffset(3)).  The beginning-of-field marker of the special field INDEX is zero.

       The beginning-of-field of a PHASE field is the beginning-of-field of its input adjusted by
       the PHASE field's shift (or zero, if the shift would make it negative).  The beginning-of-
       field for all other vector fields is the the latest beginning-of-field of any of its input
       fields.

       If  the beginning-of-field marker of a field is greather than or equal to its end-of-field
       marker (see gd_eof(3)), then that field contains no data.  For a RAW field, the difference
       between  the  locations of the beginning- and end-of-field markers indicates the number of
       samples of data actually stored on disk.

       The dirfile argument must point to a valid DIRFILE object previously created by a call  to
       gd_open(3).

RETURN VALUE

       Upon  successful  completion,  gd_bof() returns a non-negative integer which is the sample
       number of the beginning-of-field marker for the specified field.  On error, it  returns  a
       negative-valued error code.  Possible error codes are:

       GD_E_BAD_CODE
               The  field  specified  by field_code or one of the fields it uses as input was not
               found in the database.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_DIMENSION
               A scalar field was found where a vector field was expected in  the  definition  of
               field_code  or  one  of  its  inputs, or else field_code itself specified a scalar
               field.

       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 GetData
               developers.

       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.

       The error code is also stored in the DIRFILE  object  and  may  be  retrieved  after  this
       function  returns by calling gd_error(3).  A descriptive error string for the error may be
       obtained by calling gd_error_string(3).

HISTORY

       The gd_bof() function appeared in GetData-0.7.0.

       Before GetData-0.10.0, this function could also fail with the error code GD_E_ALLOC.

       In GetData-0.10.0, the error return from this function changed  from  -1  to  a  negative-
       valued error code.

SEE ALSO

       gd_eof(3),  gd_error(3),  gd_error_string(3),  gd_frameoffset(3),  gd_open(3), dirfile(5),
       dirfile-encoding(5)