trusty (3) gd_madd.3.gz

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)