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

# gd\_madd\_string(3)

add a field to a Dirfile

Part of [gd\_madd\_bit(3)](/gd_madd_bit/3.md).

## NAME

gd\_madd\_bit, gd\_madd\_carray, gd\_madd\_clincom, gd\_madd\_const, gd\_madd\_cpolynom, gd\_madd\_crecip, gd\_madd\_divide, gd\_madd\_indir, gd\_madd\_lincom, gd\_madd\_linterp, gd\_madd\_multiply, gd\_madd\_phase, gd\_madd\_polynom, gd\_madd\_recip, gd\_madd\_sarray, gd\_madd\_sbit, gd\_madd\_sindir, gd\_madd\_string — add a field to a Dirfile

## SYNOPSIS

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

**int gd\_madd\_bit(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **const char \****in\_field***, int** *bitnum***, int** *numbits***);**

**int gd\_madd\_carray(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **gd\_type\_t** *const\_type***, size\_t** *array\_len***, gd\_type\_t** *data\_type***,** **void \****value***);**

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

**int gd\_madd\_const(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **gd\_type\_t** *const\_type***, gd\_type\_t** *data\_type***, void \****value***);**

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

**int gd\_madd\_crecip(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, const char \****in\_field***,** **double complex** *cdividend***, int** *fragment\_index***);**

**int gd\_madd\_divide(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,**  **const char \****in\_field1***, const char \****in\_field2***);**

**int gd\_madd\_indir(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,**  **const char \****index\_field***, const char \****carray\_field***);**

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

**int gd\_madd\_linterp(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **const char \****in\_field***, const char \****table***);**

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

**int gd\_madd\_multiply(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,**  **const char \****in\_field1***, const char \****in\_field2***);**

**int gd\_madd\_polynom(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, int** *poly\_ord***, const char \****in\_field***,** **const double \****a***);**

**int gd\_madd\_phase(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **const char \****in\_field***, gd\_int64\_t** *shift***);**

**int gd\_madd\_recip(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, const char \****in\_field***,** **double** *dividend***, int** *fragment\_index***);**

**int gd\_madd\_sarray(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **size\_t** *array\_len* **,***const***char***\*\*"***value***);*

**int gd\_madd\_sbit(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,** **const char \****in\_field***, int** *bitnum***, int** *numbits***);**

**int gd\_madd\_sindir(DIRFILE \****dirfile***,** **const char \****parent***, const char \****field\_name***,**  **const char \****index\_field***, const char \****sarray\_field***);**

**int gd\_madd\_string(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, const char \****value***);**

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

## DESCRIPTION

These functions add a new metafield of the indicated type under the parent field given by *parent* to the dirfile specified by *dirfile*.

In all of these calls, *field\_name* indicates the name of the field to be added.  It should not be the full *\<parent-field\>***/***\<meta-field\>* field code.  The meaning and valid types of other arguments may be obtained from the [**gd\_entry**(3)](/gd_entry/3.md) and [dirfile-format(5)](/dirfile-format/5.md) manual pages.

The **gd\_madd\_clincom**() and **gd\_madd\_cpolynom**() functions are identical to **gd\_madd\_lincom**() and **gd\_madd\_polynom**(), except they take complex scalar parameters, instead of purely real values.

The **gd\_madd\_lincom**() and **gd\_madd\_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\_madd\_polynom**() and **gd\_madd\_cpolynom**() take an array of length *poly\_ord* + 1 containing the polynomial co-efficients (*a* or *ca*).

The **gd\_madd\_carray**(), **gd\_madd\_const**(), **gd\_madd\_sarray**(), and **gd\_madd\_string**(), functions both add the field and set the value of the field to *value*. For **gd\_madd\_const**() and **gd\_madd\_carray**(), the *const\_type* argument specifies the storage type for the const, while *data\_type* specifies the data type of the value pointed to by *value*. For **gd\_madd\_sarray**(), *value* should contain *array\_len* string pointers.

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.

All fields added with this interface must contain numerical parameters.  Fields with scalar fields as parameters cannot be added with these functions.  Those fields must be added with [**gd\_madd**(3)](/gd_madd/3.md) or [**gd\_madd\_spec**(3)](/gd_madd_spec/3.md). See [**gd\_add\_bit**(3)](/gd_add_bit/3.md), &c. for an alternate way of adding metafields with explicit parameters.

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

## RETURN VALUE

On success, any of these functions returns 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\_name* argument contained invalid characters. Alternately, the *parent* field code was not found, or was already a metafield.\
  .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\_TYPE** The *data\_type* or *const\_type* argument provided to **gd\_madd\_const**() or **gd\_madd\_carray**() was invalid.\
  .TP 8 **GD\_E\_DUPLICATE** The *field\_name* provided duplicated that of an already existing field.\
  .TP 8 **GD\_E\_PROTECTED** The metadata of the fragment was protected from change.

The dirfile error may also 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).

## NOTES

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

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

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

**int gd\_madd\_cpolynom(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, int** *poly\_ord***, const char \****in\_field***,** **const double \****ca***);**

**int gd\_madd\_crecip(DIRFILE \****dirfile***, const char \****parent***,** **const char \****field\_name***, const char \****in\_field***,** **double** *cdividend\[2\]***, int** *fragment\_index***);**

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\_madd\_clincom**() and **gd\_madd\_cpolynom**(), these are simply different (but equivalent) declarations of the C99 function entry point.  For **gd\_madd\_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\_madd\_crecip**() is always available, and may be accessed as **gd\_madd\_crecip89**(), with the C89 prototype, in both the C99 and C89 APIs.

## HISTORY

The functions **dirfile\_madd\_bit**(), **dirfile\_madd\_const**(), **dirfile\_madd\_lincom**(), **dirfile\_madd\_linterp**(), **dirfile\_madd\_multiply**(), **dirfile\_madd\_phase**(), and **dirfile\_madd\_string**() appeared in GetData-0.4.0.

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

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

In GetData-0.8.0, these functions first allowed adding metafields by providing the full (slashed) field name.  The functions **gd\_madd\_mplex**() and **gd\_madd\_window**() also appeared in this version.

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

## SEE ALSO

the corresponding **gd\_add\_**\<entry-type\> functions (e.g. [**gd\_add\_bit**(3)](/gd_add_bit/3.md)), [**gd\_entry**(3)](/gd_entry/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_madd**(3)](/gd_madd/3.md), [**gd\_madd\_spec**(3)](/gd_madd_spec/3.md), [**gd\_metaflush**(3)](/gd_metaflush/3.md), [**gd\_open**(3)](/gd_open/3.md), [dirfile-format(5)](/dirfile-format/5.md)