.\" 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_fragment_affixes.3.  The gd_fragment_affixes man page.
.\"
.\" Copyright (C) 2012, 2015, 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_fragment_affixes 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_fragment_affixes \(em report the field affixes of a fragment of a Dirfile database

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

.SH DESCRIPTION
The
.FN gd_fragment_affixes
function queries a dirfile(5) database specified by
.ARG dirfile
and returns the field affixes for the fragment indexed by
.ARG fragment_index .
The field prefix and suffix are appended to all field codes found in the
specified fragment.

The
.ARG prefix
and
.ARG suffix
parameters point to memory locations in which store the addresses of the
returned strings.  The returned
.ARG prefix
does NOT contain the root namespace of the fragment.  To retreive that, use
.F3 gd_fragment_namespace .

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_fragment_affixes
returns zero.  If non-empty, the prefix and suffix are reported in
heap-allocated buffers whose addresses are returned in
.BI * prefix
and
.BI * suffix\fR.
By default
.F3 malloc
is used to allocate these buffers, but a different allocator may be specified
by calling
.F3 gd_alloc_funcs
before calling this function.  The caller is responsible for deallocating the
buffers.  If the fragment prefix or suffix is the empty string, NULL is
returned in the corresponding pointer.

On error, a negative-valued error code is returned.  In this case, the values of
.BI * prefix
and
.BI * suffix
are unspecified, but will NOT be pointers to valid allocated memory.  Possible
returned error codes are:
.DD GD_E_ALLOC
A memory allocation error occurred.
.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 gd_fragment_affixes
function appeared in GetData-0.8.0.

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_alloc_funcs ,
.F3 gd_alter_affixes ,
.F3 gd_fragment_namespace ,
.F3 gd_include_affixes ,
.F3 gd_open ,
dirfile(5),
dirfile-format(5)