gd_add(3) GETDATA gd_add(3)NAME
gd_add, gd_madd — add a field to a dirfile
SYNOPSIS
#include <getdata.h>
int gd_add(DIRFILE *dirfile, const gd_entry_t *entry);
int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char
*parent);
DESCRIPTION
The gd_add() function adds the field described by entry to the dirfile
specified by dirfile. The gd_madd() function behaves similarly, but
adds the field as a metafield under the field indicated by the field
code parent.
The form of entry is described in detail on the gd_entry(3) man page.
All relevant members of entry for the field type specified must be
properly initialised. If entry specifies a CONST or CARRAY field, the
field's data will be set to zero. If entry specifies a STRING field,
the field data will be set to the empty string.
A metafield may be added either by calling gd_madd() with entry->field
containing only the metafield's name, or else by calling gd_add() with
the fully formed <parent-field>/<meta-field> field code in en‐
try->field. Regardless of which interface is used, when adding a
metafield the value of entry->fragment_index is ignored and GetData
will add the new metafield to the same format specification fragment in
which the parent field is defined. If the specified parent field name
is an alias, the canonical name of the field will be substituted.
Fields added with this interface may contain either literal parameters
or parameters based on scalar fields. If an element of the en‐
try->scalar array defined for the specified field type is non-NULL,
this element will be used as the scalar field code, and the correspond‐
ing numerical member will be ignored, and need not be initialised.
Conversely, if numerical parameters are intended, the corresponding en‐
try->scalar elements should be set to NULL. If using an element of a
CARRAY field, entry->scalar_ind should also be set.
RETURN VALUE
On success, gd_add() and gd_madd() return zero. On error, -1 is re‐
turned and the dirfile error is set to a non-zero error value. Possi‐
ble error values are:
GD_E_ACCMODE
The specified dirfile was opened read-only.
GD_E_ALLOC
The library was unable to allocate memory.
GD_E_BAD_CODE
The field name provided in entry->field contained invalid char‐
acters; or it or an input field did not contain the affected
fragment's prefix or suffix. Alternately, the parent field code
was not found, or was already a metafield.
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
GD_E_BAD_ENTRY
There was an error in the specification of the field described
by entry, or the caller attempted to add a field of type RAW as
a metafield.
GD_E_BAD_INDEX
The entry->fragment_index parameter was out of range.
GD_E_BAD_TYPE
The entry->data_type parameter provided with a RAW entry, or
the entry->const_type parameter provided with a CONST or CARRAY
entry, was invalid.
GD_E_BOUNDS
The entry->array_len parameter provided with a CARRAY entry was
greater than GD_MAX_CARRAY_LENGTH.
GD_E_DUPLICATE
The field name provided in entry->field duplicated that of an
already existing field.
GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to per‐
form the task. This indicates a bug in the library. Please
report the incident to the GetData developers.
GD_E_PROTECTED
The metadata of the fragment was protected from change. Or,
the creation of a RAW field was attempted and the data of the
fragment was protected.
GD_E_RAW_IO
An I/O error occurred while creating an empty binary file to be
associated with a newly added RAW field.
GD_E_UNKNOWN_ENCODING
The encoding scheme of the indicated format specification frag‐
ment 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 RAW field.
GD_E_UNSUPPORTED
The encoding scheme of the indicated format specification frag‐
ment does not support creating an empty binary file to be asso‐
ciated with a newly added RAW field.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
NOTES
GetData artificially limits the number of elements in a CARRAY to the
value of the symbol GD_MAX_CARRAY_LENGTH defined in getdata.h. This is
done to be certain that the CARRAY won't overrun the line when flushed
to disk. On a 32-bit system, this number is 2**24. It is larger on a
64-bit system.
SEE ALSOgd_add_bit(3), gd_add_carray(3), gd_add_const(3), gd_add_divide(3),
gd_add_lincom(3), gd_add_linterp(3), gd_add_multiply(3),
gd_add_phase(3), gd_add_polynom(3), gd_add_raw(3), gd_add_recip(3),
gd_add_sbit(3), gd_add_spec(3), gd_add_string(3), gd_entry(3), gd_er‐
ror(3), gd_error_string(3), gd_madd_bit(3), gd_madd_carray(3),
gd_madd_const(3), gd_madd_divide(3), gd_madd_lincom(3), gd_madd_lin‐
terp(3), gd_madd_multiply(3), gd_madd_phase(3), gd_madd_polynom(3),
gd_madd_recip(3), gd_madd_sbit(3), gd_madd_spec(3), gd_madd_string(3),
gd_metaflush(3), gd_open(3), dirfile-format(5)Version 0.8.1 26 July 2012 gd_add(3)
