NAME

       gd_reference — retrieve or set the reference field for a Dirfile

SYNOPSIS

       #include <getdata.h>

       const char *gd_reference(DIRFILE *dirfile, const char *field_code);

DESCRIPTION

       The  gd_reference()  function  sets  or  retrieves  the  reference  field (see dirfile(5))
       associated with the dirfile specified by dirfile.  If the field_code argument is non-NULL,
       the  reference field for the dirfile will be set to the field specified.  If field_code is
       NULL, the reference field is not modified.  The field code should refer to  a  RAW  field,
       and may not contain a representation suffix.

RETURN VALUE

       On  success, gd_reference() returns the field code of the dirfile's reference field, which
       will be field_code, if field_code is non-NULL.   If no  RAW  fields  are  defined  in  the
       dirfile,  this  function  will  return  NULL, without raising an error.  On error, NULL 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 specified by field_code was not found.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_FIELD_TYPE
               The field specified by field_code was not a RAW field.

       GD_E_PROTECTED
               The  metadata  of the primary format specification fragment (the file named format
               in the root dirfile directory) was protected from change.

       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).

HISTORY

       The  get_reference()  function appeared in GetData-0.4.2.  It took only one parameter (the
       DIRFILE), and returned the current reference field.

       The dirfile_reference() function appeared in GetData-0.5.0.

       In GetData-0.7.0, the dirfile_reference() function was renamed to gd_reference()  and  the
       get_reference() function was removed.

SEE ALSO

       gd_error(3),   gd_error_string(3),   gd_metaflush(3),   gd_open(3),  dirfile(5),  dirfile-
       format(5)