.\" gd_parent_fragment.3.  The gd_parent_fragment man page.
.\"
.\" Copyright (C) 2008, 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_parent_fragment 3 "21 July 2010" "Version 0.7.0" "GETDATA"
.SH NAME
gd_parent_fragment \(em retrieve the parent fragment of a fragment in a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_parent_fragment(const DIRFILE *" dirfile ", int " fragment_index );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_parent_fragment ()
function queries a dirfile(5) database specified by
.I dirfile
and returns the index of the fragment which contains the
.B INCLUDE
directive for the fragment indexed by
.IR fragment_index .

Since the primary format specification fragment is not included in any other
fragment, passing zero for
.I fragment_index
will result in an error.

.SH RETURN VALUE
On success,
.BR gd_parent_fragment ()
returns the index of the specified fragment's parent.  On error,
.BR gd_parent_fragment ()
returns -1 and sets the dirfile error to a non-zero value.  Possible error
values are:
.TP 8
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The supplied index was out of range, or was equal to zero.
.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 gd_include (3),
.BR gd_open (3),
.BR gd_fragmentname (3),
.BR gd_nfragments (3)