---
name: "gd_alter_bit"
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_bit"
---

# gd\_alter\_bit(3)

modify a field in a Dirfile

## NAME

gd\_alter\_bit, gd\_alter\_carray, gd\_alter\_clincom, gd\_alter\_const, gd\_alter\_cpolynom, gd\_alter\_crecip, gd\_alter\_divide, gd\_alter\_indir, gd\_alter\_lincom, gd\_alter\_linterp, gd\_alter\_multiply, gd\_alter\_phase, gd\_alter\_polynom, gd\_alter\_raw, gd\_alter\_recip, gd\_alter\_sarray, gd\_alter\_sbit, gd\_alter\_sindir — modify a field in a Dirfile

## SYNOPSIS

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

**int gd\_alter\_bit(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, int** *bitnum***, int** *numbits***);**

**int gd\_alter\_carray(DIRFILE \****dirfile***, const char \****field\_code***,** **gd\_type\_t** *const\_type***, size\_t** *array\_len***);**

**int gd\_alter\_clincom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *n\_fields***, const char \*\****in\_fields***, const double complex \****cm***,** **const double complex \****cb***);**

**int gd\_alter\_const(DIRFILE \****dirfile***, const char \****field\_code***,** **gd\_type\_t** *const\_type***);**

**int gd\_alter\_cpolynom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *poly\_ord***, const char \****in\_field***, const double complex \****ca***);**

**int gd\_alter\_crecip(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, complex double** *cdividend***);**

**int gd\_alter\_divide(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field1***, const char \****in\_field2***);**

**int gd\_alter\_indir(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****index\_field***, const char \****carray\_field***);**

**int gd\_alter\_lincom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *n\_fields***, const char \*\****in\_fields***, const double \****m***,** **const double \****b***);**

**int gd\_alter\_linterp(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, const char \****table***, int** *rename\_table***);**

**int gd\_alter\_mplex(DIRFILE \****dirfile***, const char \****field\_name***,** **const char \****in\_field***, const char \****count\_field***,** **int** *count\_val***, int** *period***);**

**int gd\_alter\_multiply(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field1***, const char \****in\_field2***);**

**int gd\_alter\_phase(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, gd\_int64\_t** *shift***);**

**int gd\_alter\_polynom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *poly\_ord***, const char \****in\_field***, const double \****ca***);**

**int gd\_alter\_raw(DIRFILE \****dirfile***, const char \****field\_code***,** **gd\_type\_t** *data\_type***, unsigned int** *spf***, int** *recode***);**

**int gd\_alter\_recip(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, double** *dividend***);**

**int gd\_alter\_sarray(DIRFILE \****dirfile***, const char \****field\_code***,** **size\_t** *array\_len***);**

**int gd\_alter\_sbit(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, int** *bitnum***, int** *numbits***);**

**int gd\_alter\_sindir(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****index\_field***, const char \****sarray\_field***);**

**int gd\_alter\_window(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, const char \****check\_field***,** **gd\_windop\_t** *windop***, gd\_triplet\_t** *threshold***);**

## DESCRIPTION

These functions provide alternatives to using the [**gd\_alter\_entry**(3)](/gd_alter_entry/3.md) function to modify a field of the indicated type in the dirfile specified by *dirfile*.

In all of these calls, *field\_code* indicates the the field to be modified, which may be a regular field, or a metafield specified by its full (slashed) field code, but should not contain a representation suffix.  The meaning and valid types of other arguments may be obtained from the **get\_entry**(3) and [dirfile-format(5)](/dirfile-format/5.md) manual pages.  The **gd\_int64\_t** type is a signed 64-bit integer type.  The **gd\_triplet\_t** type is defined as:

```
typedef union {
  gd_int64_t i;
  gd_uint64_t u;
  double r;
} gd_triplet_t;
```

Which element of this **gd\_triplet\_t** union to set depends on the operator selected for the **WINDOW** field.  See [**gd\_entry**(3)](/gd_entry/3.md) for details.

The **gd\_alter\_clincom**() and **gd\_alter\_cpolynom**() functions are identical to **gd\_alter\_lincom**() and **gd\_alter\_polynom**(), except they take complex scalar parameters, instead of purely real values.  This only matters for the input of *new* parameters; if the scalar parameters are not changed (by passing NULL instead of a list of scalars), the functions can be used interchangeably, regardless of whether the altered field has complex scalar parameters or not.

If the corresponding parameters are to be changed, the **gd\_alter\_lincom**() and **gd\_alter\_clincom**() functions take pointers to three arrays of length *n\_fields* containing the input field names (*in\_fields*), the gain factors (*m* or *cm*), and the offset terms (*b* or *cb*). Similarly, **gd\_alter\_polynom**() and **gd\_alter\_cpolynom**() take an array of length *poly\_ord* + 1 containing the polynomial co-efficients (*a* or *ca*).

Some field parameters have special values which indicate no change should be made to the parameter.  These special values are:\
  .TP 8 **NULL:** any of the string parameters, also  *m*, *b*, *a*, *cm*, *cb*, or *ca*;\
  .TP 8 **0:** *spf*, *n\_fields*, *numbits*, *cdividend*, *dividend*, or *array\_len*;\
  .TP 8 **-1:** *bitnum* or *period*;\
  .TP 8 **GD\_NULL:** *data\_type* or *const\_type*;\
  .TP 8 **GD\_WINDOP\_UNK:** *windop*.

All field parameters introduced with this interface must contain literal parameters.  Field parameters which are scalar fields cannot be introduced with these functions.  To do that, use [**gd\_alter\_entry**(3)](/gd_alter_entry/3.md), [**gd\_alter\_spec**(3)](/gd_alter_spec/3.md) or [**gd\_malter\_spec**(3)](/gd_malter_spec/3.md), as appropriate.

If *rename\_table* is non-zero, the look-up table referenced by the **LINTERP** field will be renamed to the path given by *table*. If *recode* is non-zero, the binary file associated with the **RAW** field will be re-encoded to reflect the new field parameters.  In this case, the field's I/O pointer will be reset to the beginning-of-frame.

If **gd\_alter\_carray**() is used to increase the length of a **CARRAY** field, the added elements will be uninitialised.  Use [**gd\_put\_carray\_slice**(3)](/gd_put_carray_slice/3.md) or equivalent to initialise them.  Similarly, increasing the length of a **SARRAY** with **gd\_alter\_sarray**() will set the added elements to the empty string ("").  Use [**gd\_put\_sarray\_slice**(3)](/gd_put_sarray_slice/3.md) or equivalent to modify them.

See **NOTES** below for information on using **gd\_alter\_clincom**(), **gd\_alter\_crecip**(), and  **gd\_alter\_cpolynom**() in the C89 GetData API.

## RETURN VALUE

On success, these functions return zero.  On error, a negative-valued error code is returned.  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 by *field\_code* was not found, or a supplied field code did not contain the appropriate prefix or suffix.\
  .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\
  .TP 8 **GD\_E\_BAD\_ENTRY** One or more of the field parameters specified was invalid.\
  .TP 8 **GD\_E\_BAD\_FIELD\_TYPE** The field specified by *field\_code* was of the wrong type for the function called.\
  .TP 8 **GD\_E\_BAD\_TYPE** The *data\_type* *const\_type* argument was invalid.\
  .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\_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 binary file associated with a modified **RAW** field.

The error code is also stored in the **DIRFILE** object and may be retrieved after these functions return 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).

## NOTES

The C89 GetData API provides different prototypes for **gd\_alter\_clincom**(), **gd\_alter\_cpolynom**(), and **gd\_alter\_crecip**():

**#define GD\_C89\_API**\
 **#include \<getdata.h\>**

**int gd\_alter\_clincom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *n\_fields***, const char \*\****in\_fields***, const double \****cm***,** **const double \****cb***);**

**int gd\_alter\_cpolynom(DIRFILE \****dirfile***, const char \****field\_code***,** **int** *poly\_ord***, const char \****in\_fields***, const double \****ca***);**

**int gd\_alter\_crecip(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \****in\_field***, const double** *cdividend\[2\]***);**

In this case, the array pointers passed as *cm*, *cb* or *ca* should have twice as many (purely real) elements, consisting of alternating real and imaginary parts for the complex data.  That is, for example, *ca*\[0\] should be the real part of the first co-efficient, *ca*\[1\] the imaginary part of the first co-efficient, *ca*\[2\] the real part of the second co-efficient, *ca*\[3\] the imaginary part of the second co-efficient, and so on.  Similarly, the *cdividend* parameter becomes a double precision array of length two.

For **gd\_alter\_clincom**() and **gd\_alter\_cpolynom**(), these are simply different (but equivalent) declarations of the C99 function entry point.  For **gd\_alter\_crecip**(), however, a different entry point is needed (since the *cdividend* parameter is passed by reference instead of by value).  In the interests of portability, the C89 version of **gd\_alter\_crecip**() is always available, and may be accessed as **gd\_alter\_crecip89**(), with the C89 prototype, in both the C99 and C89 APIs.  Passing NULL as *cdividend* is equivalent to specifying a dividend of zero: it indicates no change to the dividend parameter.

## HISTORY

The functions **dirfile\_alter\_bit**(), **dirfile\_alter\_const**(), **dirfile\_alter\_lincom**(), **dirfile\_alter\_linterp**(), **dirfile\_alter\_multiply**(), **dirfile\_alter\_phase**(), and **dirfile\_alter\_raw**() appeared in GetData-0.5.0.

The functions **dirfile\_alter\_clincom**(), **dirfile\_alter\_cpolynom**(), **dirfile\_alter\_polynom**(), and **dirfile\_alter\_sbit**() appeared in GetData-0.6.0.

In GetData-0.7.0, the functions were renamed to **gd\_alter\_bit**(), **gd\_alter\_clincom**(), **gd\_alter\_const**(), **gd\_alter\_cpolynom**(), **gd\_alter\_lincom**(), **gd\_alter\_linterp**(), **gd\_alter\_multiply**(), **gd\_alter\_phase**(), **gd\_alter\_polynom**(), **gd\_alter\_raw**(), and **gd\_alter\_sbit**(). The functions **gd\_alter\_carray**(), **gd\_alter\_crecip**(), **gd\_alter\_crecip89**(), **gd\_alter\_divide**(), and **gd\_alter\_recip**() also appeared in this version.

The functions **gd\_alter\_mplex**() and **gd\_alter\_window**() appeared in GetData-0.8.0.

In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code.  The functions **gd\_alter\_indir**(), **gd\_alter\_sarray**(), and **gd\_alter\_sindir**() also appeared in this version.

## SEE ALSO

[**gd\_alter\_entry**(3)](/gd_alter_entry/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\_malter\_spec**(3)](/gd_malter_spec/3.md), [**gd\_metaflush**(3)](/gd_metaflush/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_put\_carray\_slice**(3)](/gd_put_carray_slice/3.md), [**gd\_put\_sarray\_slice**(3)](/gd_put_sarray_slice/3.md), [dirfile-format(5)](/dirfile-format/5.md)