.\" gd_bof.3.  The gd_bof man page.
.\"
.\" Copyright (C) 2010 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_bof 3 "15 October 2010" "Version 0.7.0" "GETDATA"
.SH NAME
gd_bof \(em report the start of data in a field
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "off_t gd_bof(DIRFILE *" dirfile ", const char *" field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_bof ()
function queries a dirfile(5) database specified by
.I dirfile
and returns the sample number of the beginning-of-field marker for the vector
field given by
.IR 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
.B RAW
field, the beginning-of-field corresponds to the frame offset of that field
(see
.BR gd_frameoffset (3)).
The beginning-of-field for all other vector field type is the same as the
beginning-of-field of whichever of its input fields that starts latest.  The
beginning-of-field marker for the special field
.I INDEX
is always zero.

The beginning-of-field marker for a field containing no data is in the same
location as, or after, its end-of-field marker (see
.BR gd_eof (3)).
For a
.B 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 
.I dirfile
argument must point to a valid DIRFILE object previously created by a call to
.BR gd_open (3).

.SH RETURN VALUE
Upon successful completion,
.BR gd_bof ()
returns the sample number of the end-of-field marker for the indicated field.
On error, it returns -1 and sets the dirfile error to a non-zero error value.
Possible error values are:
.TP 8
.B GD_E_BAD_CODE
The field specified by
.I field_code
or one of the fields it uses as input was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_REPR
The representation suffix specified in
.IR field_code ,
or in one of its inputs was not recognised.
.TP
.B GD_E_DIMENSION
A scalar field was found where a vector field was expected in the definition
of
.I field_code 
or one of its inputs, or else
.I field_code
itself specified a scalar field.
.TP
.B GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.IR field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).
.SH SEE ALSO
.BR dirfile (5),
.BR dirfile-encoding (5),
.BR gd_open (3),
.BR gd_eof (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_nframes (3)