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

# gd\_alter\_spec(3)

modify a field in a Dirfile

## NAME

gd\_alter\_spec, gd\_malter\_spec — modify a field in a Dirfile

## SYNOPSIS

**#include \<getdata.h\>**

**int gd\_alter\_spec(DIRFILE \****dirfile***, const char \****line***,** **int** *recode***);**

**int gd\_malter\_spec(DIRFILE \****dirfile***, const char \****line***,** **const char \****parent***, int** *recode***);**

## DESCRIPTION

The **gd\_alter\_spec**() function modifies the field described by the field specification line in *line* to the dirfile specified by *dirfile*. The **gd\_malter\_spec**() function behaves similarly, but modifies the metafield under the field indicated by the field code *parent*. Field specification lines are described in detail in [dirfile-format(5)](/dirfile-format/5.md).

The name of the field to be modified, which must already exist, will be obtained from the field specification line.  When adding a metafield,  *line* should only contain a field specification, and not a **/META** directive.

If the modified field is of type **RAW** and the *recode* argument is non-zero, the binary file associated with the field will be converted for changes in data type and samples-per-frame.  In this case, the field's I/O pointer will be reset to the beginning-of-frame.  If *recode* is zero, no binary file conversion will take place.

If the modified field is of type **LINTERP** and the *recode* argument is non-zero, the look-up table file will be moved if *line* specifies a different path, overwriting an existing file with the new pathname, if present.  If the field specified by *field\_code* is of type other than **RAW** or **LINTERP**, the *recode* argument is ignored.

Passing these functions a directive line instead of a field specification line will result in a syntax error.  These functions never call the registered parser callback function, even if *line* contains a syntax error.

## RETURN VALUE

On success, **gd\_alter\_spec**() and **gd\_malter\_spec**() return zero.  On error, it returns a negative-valued error code.  Possible error codes 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 in *line* was not found, or the *parent* field code was not found.\
  .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\
  .TP 8 **GD\_E\_FORMAT** A syntax error was encountered in *line*.\
  .TP 8 **GD\_E\_IO** An I/O error occurred while translating the binary file associated with a modified **RAW** field, or an I/O error occurred while attempting to rename a **LINTERP** table file.\
  .TP 8 **GD\_E\_LINE\_TOO\_LONG** The supplied *line* was longer than the parser was able to deal with.  Line lengths are limited by the storage size of **size\_t**.\
  .TP 8 **GD\_E\_PROTECTED** The metadata of the fragment was protected from change.  Or, a request to translate the binary file associated with a **RAW** field was attempted, but the data of the fragment was protected.\
  .TP 8 **GD\_E\_UNKNOWN\_ENCODING** The encoding scheme of the indicated format specification fragment is not known to the library.  As a result, the library was unable to translate the binary file be associated with a modified **RAW** field.\
  .TP 8 **GD\_E\_UNSUPPORTED** The encoding scheme of the indicated format specification fragment does not support translating the empty binary file associated with a modified **RAW** field.

The error code is also stored in the **DIRFILE** object and may be retrieved after this function returns by calling [**gd\_error**(3)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md).

## HISTORY

The functions **dirfile\_alter\_spec**() and **dirfile\_malter\_spec**() appeared in GetData-0.5.0.

In GetData-0.7.0, these functions were renamed to **gd\_alter\_spec**() and **gd\_malter\_spec.**()

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

## SEE ALSO

Any of the **gd\_alter\_**\<entry-type\> functions (e.g., [**gd\_alter\_bit**(3)](/gd_alter_bit/3.md)), [**gd\_alter\_spec**(3)](/gd_alter_spec/3.md), [**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-format(5)](/dirfile-format/5.md)