---
name: "gd_reference"
section: "3"
platform: "linux"
package: "libgetdata-doc"
version: "0.11.0-15"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gd_reference"
---

# gd\_reference(3)

retrieve or set the reference field for a Dirfile

## 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)](/dirfile/5.md)) 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:\
  .TP 8 **GD\_E\_ACCMODE** The specified dirfile was opened read-only.\
  .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\
  .TP 8 **GD\_E\_BAD\_CODE** The field specified by *field\_code* was not found.\
  .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\
  .TP 8 **GD\_E\_BAD\_FIELD\_TYPE** The field specified by *field\_code* was not a **RAW** field.\
  .TP 8 **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)](/gd_error/3.md). A descriptive error string for the last error encountered can be obtained from a call to [**gd\_error\_string**(3)](/gd_error_string/3.md).

## 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/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_metaflush**(3)](/gd_metaflush/3.md), [**gd\_open**(3)](/gd_open/3.md), [dirfile(5)](/dirfile/5.md), [dirfile-format(5)](/dirfile-format/5.md)