.\" gd_add_spec.3.  The gd_add_spec man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2014 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 "16 October 2014" "Version 0.9.0" "GETDATA"
.SH NAME
gd_add_spec, gd_madd_spec \(em add a field to a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.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 );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_add_spec ()
function adds the field described by the field specification line in
.I line
to the dirfile specified by
.IR dirfile .
The
.BR gd_madd_spec ()
function behaves similarly, but adds the field as a metafield under the
field indicated by the field
.IR parent .
Field specification lines are described in detail in
.BR dirfile-format (5).
Since Standards Version 7 (see dirfile(5)) permits specifying metafield without
the use of the
.B /META
directive,
.BR 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
.BR gd_madd_spec (),
.I 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
.IR line 
contains a syntax error.

.SH RETURN VALUE
On success,
.BR gd_add_spec ()
and
.BR gd_madd_spec ()
return zero.   On error, -1 is returned and the dirfile error is set to a
non-zero error value.  Possible error values are:
.TP 8
.B GD_E_ACCMODE
The specified dirfile was opened read-only.
.TP
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_CODE
The
.I parent
field code was not found, or was already a metafield.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The
.IR fragment_index
argument was out of range.
.TP
.B GD_E_FORMAT
A syntax error was encountered in
.IR line .
.TP
.B GD_E_IO
An I/O error occurred while creating an empty binary file to be associated with
a newly added
.B RAW
field.
.TP
.B GD_E_LINE_TOO_LONG
The supplied
.I line
was longer than the parser was able to deal with.  Lines are limited by the
storage size of
.BR ssize_t .
On 32-bit systems, this limits
.I line
to 2**31 bytes.  The limit is larger on 64-bit systems.
.TP
.B 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.
.TP
.B 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.
.TP
.B 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 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 gd_add (3),
.BR gd_add_bit (3),
.BR gd_add_carray (3),
.BR gd_add_const (3),
.BR gd_add_divide (3),
.BR gd_add_lincom (3),
.BR gd_add_linterp (3),
.BR gd_add_multiply (3),
.BR gd_add_phase (3),
.BR gd_add_recip (3),
.BR gd_add_raw (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_madd (3),
.BR gd_madd_bit (3),
.BR gd_madd_carray (3),
.BR gd_madd_const (3),
.BR gd_madd_divide (3),
.BR gd_madd_lincom (3),
.BR gd_madd_linterp (3),
.BR gd_madd_multiply (3),
.BR gd_madd_phase (3),
.BR gd_madd_polynom (3),
.BR gd_madd_recip (3),
.BR gd_madd_string (3),
.BR gd_metaflush (3),
.BR gd_open (3),
.BR dirfile-format (5)