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

SEE ALSO

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