.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 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.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_bof.3.  The gd_bof man page.
.\"
.\" Copyright (C) 2010, 2011, 2016 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 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_bof \(em find the start of data in a Dirfile field

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "off_t gd_bof(DIRFILE *" dirfile ", const char *" field_code );
.EC

.SH DESCRIPTION
The
.FN gd_bof
function queries a dirfile(5) database specified by
.ARG dirfile
and finds the beginning-of-field marker for the vector field given by
.ARG 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
.F3 gd_frameoffset ).
The beginning-of-field marker of the special field
.I INDEX
is zero.

The beginning-of-field of a
.B PHASE
field is the beginning-of-field of its input adjusted by the
.B 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
.F3 gd_eof ),
then that field contains no data.  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 
.ARG dirfile
argument must point to a valid DIRFILE object previously created by a call to
.F3 gd_open .

.SH RETURN VALUE
Upon successful completion,
.FN 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:
.DD GD_E_BAD_CODE
The field specified by
.ARG field_code
or one of the fields it uses as input was not found in the database.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_DIMENSION
A scalar field was found where a vector field was expected in the definition
of
.ARG field_code 
or one of its inputs, or else
.ARG field_code
itself specified a scalar field.
.DD 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.
.DD GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.ARG field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.PP
The error code is also stored in the
.B DIRFILE
object and may be retrieved after this function returns by calling
.F3 gd_error .
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH HISTORY
The
.FN gd_bof
function appeared in GetData-0.7.0.

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

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

.SH SEE ALSO
.F3 gd_eof ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_frameoffset ,
.F3 gd_open ,
dirfile(5), dirfile-encoding(5)