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

.SH NAME
gd_add_spec, gd_madd_spec \(em add a field to a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_add_spec(DIRFILE *" dirfile ", const char *" line ,
.BI "int " fragment_index );
.HP
.BI "int gd_madd_spec(DIRFILE *" dirfile ", const char *" line ,
.BI "const char *" parent );
.EC

.SH DESCRIPTION
The
.FN gd_add_spec
function adds the field described by the field specification line in
.ARG line
to the dirfile specified by
.ARG dirfile .
The
.FN gd_madd_spec
function behaves similarly, but adds the field as a metafield under the
field indicated by the field
.ARG parent .
Field specification lines are described in detail in dirfile-format(5).
Since Standards Version 7 (see dirfile(5)) permits specifying metafield without
the use of the
.B /META
directive,
.FN gd_add_spec
may also be used to add metafields, by specifying the metafield's full field
code.  See dirfile-format(5) for full details.

When using
.FN gd_madd_spec ,
.ARG line
should only contain a field specification, and not a
.B /META
directive.

Passing these functions a directive line instead of a field specification line
will result in a syntax error.  These functions never call the registered
parser callback function, even if
.ARG line 
contains a syntax error.

.SH RETURN VALUE
On success,
.FN gd_add_spec
and
.FN gd_madd_spec
return zero.   On error, a negative-valued error code is returned.  Possible
error codes are:
.DD GD_E_ACCMODE
The specified dirfile was opened read-only.
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The
.ARG parent
field code was not found, or was already a metafield.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_INDEX
The
.ARG fragment_index
argument was out of range.
.DD GD_E_FORMAT
A syntax error was encountered in
.ARG line .
.DD GD_E_IO
An I/O error occurred while creating an empty binary file to be associated with
a newly added
.B RAW
field.
.DD GD_E_LINE_TOO_LONG
The supplied
.ARG line
was longer than the parser was able to deal with.  Line lengths are limited by
the storage size of
.BR size_t .
.DD GD_E_PROTECTED
The metadata of the fragment was protected from change.  Or, the creation of a
.B RAW
field was attempted and the data of the fragment was protected.
.DD GD_E_UNKNOWN_ENCODING
The encoding scheme of the indicated format specification fragment is not known
to the library.  As a result, the library was unable to create an empty binary
file to be associated with a newly added
.B RAW
field.
.DD GD_E_UNSUPPORTED
The encoding scheme of the indicated format specification fragment does not
support creating an empty binary file to be associated with a newly added
.B RAW
field.
.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 functions
.FN dirfile_add_spec
and
.FN dirfile_madd_spec
appeared in GetData-0.4.0.

In GetData-0.7.0, these functions were renamed to
.FN gd_add_spec
and
.FN gd_madd_spec .

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

.SH SEE ALSO
.F3 gd_add ,
all the
.BR gd_add_ <entry-type>
functions (e.g.,
.F3 gd_add_bit ),
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_madd ,
all the
.BR gd_madd_ <entry-type>
functions (e.g.,
.F3 gd_madd_bit ),
.F3 gd_metaflush ,
.F3 gd_open ,
dirfile-format(5)