--- name: "gd_madd" section: "3" platform: "linux" package: "libgetdata-doc" version: "0.11.0-15" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gd_add" --- # gd\_madd(3) add a field to a Dirfile Part of [gd\_add(3)](/gd_add/3.md). ## NAME gd\_add, gd\_madd — add a field to a Dirfile ## SYNOPSIS **#include \** **int gd\_add(DIRFILE \****dirfile***, const gd\_entry\_t \****entry***);** **int gd\_madd(DIRFILE \****dirfile***, const gd\_entry\_t \****entry***,** **const char \****parent***);** ## DESCRIPTION The **gd\_add**() function adds the field described by *entry* to the dirfile specified by *dirfile*. The **gd\_madd**() function behaves similarly, but adds the field as a metafield under the field indicated by the field code *parent*. The form of *entry* is described in detail on the [**gd\_entry**(3)](/gd_entry/3.md) man page. All relevant members of *entry* for the field type specified must be properly initialised. If *entry* specifies a **CONST** or **CARRAY** field, the field's data will be set to zero. If *entry* specifies a **STRING** field, the field data will be set to the empty string. The only flags in the *entry***-\>***flags* member which are honoured are **GD\_EN\_HIDDEN**, which should be set or cleared to set the hiddenness of the entry (see [**gd\_hidden**(3)](/gd_hidden/3.md)), and **GD\_EN\_COMPSCAL**, which indicates whether scalar parameters are initialised from the complex valued or purely real member, which both are present (**LINCOM**, **POLYNOM**, **RECIP**). A metafield may be added either by calling **gd\_madd**() with *entry***-\>***field* containing only the metafield's name, or else by calling **gd\_add**() with the fully formed "*\*/*\*" field code in *entry***-\>***field.* Regardless of which interface is used, when adding a metafield the value of *entry***-\>***fragment\_index* is ignored and GetData will add the new metafield to the same format specification fragment in which the parent field is defined. If the specified parent field name is an alias, the canonical name of the field will be substituted. Fields added with this interface may contain either literal parameters or parameters based on scalar fields. If an element of the *entry***-\>***scalar* array defined for the specified field type is non-NULL, this element will be used as the scalar field code, and the corresponding numerical member will be ignored, and need not be initialised. Conversely, if numerical parameters are intended, the corresponding *entry***-\>***scalar* elements should be set to NULL. If using an element of a **CARRAY** field, *entry***-\>***scalar\_ind* should also be set. ## RETURN VALUE On success, **gd\_add**() and **gd\_madd**() 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 name provided in *entry***-\>***field* contained invalid characters; or it or an input field did not contain the affected fragment's prefix or suffix. 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** There was an error in the specification of the field described by *entry*, or the caller attempted to add a field of type **RAW** as a metafield.\ .TP 8 **GD\_E\_BAD\_INDEX** The *entry***-\>***fragment\_index* parameter was out of range.\ .TP 8 **GD\_E\_BAD\_TYPE** The *entry***-\>***data\_type* parameter provided with a **RAW** entry, or the *entry***-\>***const\_type* parameter provided with a **CONST** or **CARRAY** entry, was invalid.\ .TP 8 **GD\_E\_DUPLICATE** The field name provided in *entry***-\>***field* duplicated that of an already existing field.\ .TP 8 **GD\_E\_INTERNAL\_ERROR** An internal error occurred in the library while trying to perform the task. This indicates a bug in the library. Please report the incident to the GetData developers.\ .TP 8 **GD\_E\_IO** An I/O error occurred while creating an empty binary file to be associated with a newly added **RAW** field.\ .TP 8 **GD\_E\_PROTECTED** The metadata of the fragment was protected from change. Or, the creation of a **RAW** field was attempted and 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 create an empty binary file to be associated with a newly added **RAW** field.\ .TP 8 **GD\_E\_UNSUPPORTED** The encoding scheme of the indicated format specification fragment does not support creating an empty binary file to be associated with a newly added **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\_add**() and **dirfile\_madd**() appeared in GetData-0.4.0. In GetData-0.7.0, the functions were renamed to **gd\_add**() and **gd\_madd**(). In GetData-0.8.0, **gd\_add**() first allowed adding metafields by providing the full (slashed) field name. This was the first version supporting fragment affixes, and in this version, **gd\_add**() would apply the destination fragment's affixes to the supplied *entry***-\>***field* name. In GetData-0.8.1, this changed: **gd\_add**() now assumes *entry***-\>***field* contains the full field name, including any necessary affixes. In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. See [**gd\_entry**(3)](/gd_entry/3.md) for the history of the **gd\_entry\_t** structure. ## SEE ALSO [**gd\_add\_bit**(3)](/gd_add_bit/3.md), [**gd\_add\_carray**(3)](/gd_add_carray/3.md), [**gd\_add\_const**(3)](/gd_add_const/3.md), [**gd\_add\_divide**(3)](/gd_add_divide/3.md), [**gd\_add\_lincom**(3)](/gd_add_lincom/3.md), [**gd\_add\_linterp**(3)](/gd_add_linterp/3.md), [**gd\_add\_multiply**(3)](/gd_add_multiply/3.md), [**gd\_add\_phase**(3)](/gd_add_phase/3.md), [**gd\_add\_polynom**(3)](/gd_add_polynom/3.md), [**gd\_add\_raw**(3)](/gd_add_raw/3.md), [**gd\_add\_recip**(3)](/gd_add_recip/3.md), [**gd\_add\_sbit**(3)](/gd_add_sbit/3.md), [**gd\_add\_spec**(3)](/gd_add_spec/3.md), [**gd\_add\_string**(3)](/gd_add_string/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\_bit**(3)](/gd_madd_bit/3.md), [**gd\_madd\_carray**(3)](/gd_madd_carray/3.md), [**gd\_madd\_const**(3)](/gd_madd_const/3.md), [**gd\_madd\_divide**(3)](/gd_madd_divide/3.md), [**gd\_madd\_lincom**(3)](/gd_madd_lincom/3.md), [**gd\_madd\_linterp**(3)](/gd_madd_linterp/3.md), [**gd\_madd\_multiply**(3)](/gd_madd_multiply/3.md), [**gd\_madd\_phase**(3)](/gd_madd_phase/3.md), [**gd\_madd\_polynom**(3)](/gd_madd_polynom/3.md), [**gd\_madd\_recip**(3)](/gd_madd_recip/3.md), [**gd\_madd\_sbit**(3)](/gd_madd_sbit/3.md), [**gd\_madd\_spec**(3)](/gd_madd_spec/3.md), [**gd\_madd\_string**(3)](/gd_madd_string/3.md), [**gd\_metaflush**(3)](/gd_metaflush/3.md), [**gd\_open**(3)](/gd_open/3.md), [dirfile-format(5)](/dirfile-format/5.md)