.\" 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_frameoffset.3.  The gd_frameoffset man page.
.\"
.\" Copyright (C) 2008, 2010, 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_frameoffset 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_frameoffset \(em report the starting frame of fields in a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "off_t gd_frameoffset(DIRFILE *" dirfile ", int " fragment_index );
.EC

.SH DESCRIPTION
The
.FN gd_frameoffset
function queries a dirfile(5) database specified by
.ARG dirfile
and returns the frame offset (see dirfile-format(5)) for the fragment indexed by
.ARG fragment_index .
The frame offset of a fragment indicate the frame number of the first sample
of data stored in binary files associated with
.B RAW
fields defined in the specified fragment.  The frame offset of a fragment
containing no
.B RAW
fields is ignored.

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_frameoffset
returns a non-negative integer containing the frame offset of the specified
fragment.  On error, it returns a negative-valued error code.  Possible error
codes are:
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_INDEX
The supplied index was out of range.
.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 get_frameoffset
function appeared in GetData-0.5.0.

In GetData-0.7.0, this function was renamed to
.FN gd_frameoffset .

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_alter_frameoffset ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_open ,
dirfile(5), dirfile-format(5)