Provided by: libgetdata-doc_0.11.0-4_all bug


       gd_add, gd_madd — add a field to a Dirfile


       #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);


       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.

       The only flags in the entry->flags member  which  are  honoured  are  GD_EN_HIDDEN,  which
       should  be  set  or  cleared  to  set  the hiddenness of the entry (see gd_hidden(3)), and
       GD_EN_COMPSCAL, which indicates whether scalar parameters are initialised from the complex
       valued or purely real member, which both are present (LINCOM, POLYNOM, RECIP).

       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 entry->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

       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.


       On success, gd_add() and gd_madd() return zero.   On error, a negative-valued  error  code
       is returned.  Possible error codes are:

               The specified dirfile was opened read-only.

               The library was unable to allocate memory.

               The  field name provided in entry->field contained invalid characters; 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.

               The supplied dirfile was invalid.

               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.

               The entry->fragment_index parameter was out of range.

               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.

               The  field  name  provided  in entry->field duplicated that of an already existing

               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

       GD_E_IO An I/O error occurred while creating an empty binary file to be associated with  a
               newly added RAW field.

               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.

               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.

               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

       The error code is also stored in the DIRFILE  object  and  may  be  retrieved  after  this
       function  returns by calling gd_error(3).  A descriptive error string for the error may be
       obtained by calling gd_error_string(3).


       The functions dirfile_add() and dirfile_madd() appeared in GetData-0.4.0.

       In GetData-0.7.0, the functions were renamed to gd_add() and gd_madd().

       In GetData-0.8.0, gd_add() first allowed adding metafields by providing the full (slashed)
       field  name.  This was the first version supporting fragment affixes, and in this version,
       gd_add() would apply the destination fragment's affixes to the supplied entry->field name.
       In  GetData-0.8.1, this changed: gd_add() now assumes entry->field contains the full field
       name, including any necessary affixes.

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

       See gd_entry(3) for the history of the gd_entry_t structure.


       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)