Provided by: libgetdata-dev_0.7.3-6_i386 bug

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.

       When  adding  a  metafield, the entry->field member should contain just
       the metafield's name, not the fully formed  <parent-field>/<meta-field>
       field     code.     Also,    gd_madd()    ignores    the    value    of
       entry->fragment_index, and instead adds the new meta field to the  same
       format specification fragment in which the parent field is defined.

       Fields  added with this interface may contain either literal parameters
       or  parameters  based  on  scalar  fields.   If  an  element   of   the
       entry->scalar  array  defined for the specified field type is non-NULL,
       this  element  will  be  used  as  the  scalar  field  code,  and   the
       corresponding  numerical  member  will  be  ignored,  and  need  not be
       initialised.  Conversely, if numerical  parameters  are  intended,  the
       corresponding  entry->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
       returned  and  the  dirfile  error  is  set  to a non-zero error value.
       Possible 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
               characters.  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
               perform 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
               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 RAW field.

       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 RAW field.

       The  dirfile  error  may  be  retrieved  by  calling  gd_error(3).    A
       descriptive error string for the last error encountered can be obtained
       from a call to gd_error_string(3).

NOTES

       GetData artifically 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 ALSO

       gd_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_error(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_linterp(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)