gd_reference — retrieve or set the reference field for a Dirfile
*gd_reference(DIRFILE *dirfile, const char
() function sets or retrieves the reference field (see
dirfile(5)) associated with the dirfile specified by dirfile
. If the
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.
On success, gd_reference
() returns the field code of the dirfile's
reference field, which will be field_code
, if field_code
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:
- The specified dirfile was opened read-only.
- The library was unable to allocate memory.
- The field specified by field_code was not
- The supplied dirfile was invalid.
- The field specified by field_code was not a
- The metadata of the primary format specification fragment
(the file named format in the root dirfile directory) was protected
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
() function appeared in GetData-0.4.2. It took only one
parameter (the DIRFILE
), and returned the current reference field.
() function appeared in GetData-0.5.0.
In GetData-0.7.0, the dirfile_reference
() function was renamed to
() and the get_reference
() function was removed.
(3), dirfile(5), dirfile-format(5)