--- name: "gd_alter_entry" 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_entry" --- # gd\_alter\_entry(3) modify the metadata of a Dirfile field ## NAME gd\_alter\_entry — modify the metadata of a Dirfile field ## SYNOPSIS **#include \** **int gd\_alter\_entry(DIRFILE \****dirfile***, const char \****field\_code***,** **const gd\_entry\_t \****entry***, int** *recode***);** ## DESCRIPTION The **gd\_alter\_entry**() function modifies the field specified by *field\_code* in the dirfile specified by *dirfile* to correspond to the new parameters specified by *entry*. In addition to specifying a regular field, *field\_code* may also refer to a metafield by specifying it using its full (slashed) field code. However, *field\_code* should never contain a representation suffix. The form of *entry* is described in detail in the **get\_entry**(3) man page. The *entry***-\>***field* and *entry***-\>***fragment\_index* members are ignored by this function and need not be initialised. All other members appropriate to the field type of *field\_code* should be initialised, except as noted below. To change the fragment index of a field, use [**gd\_move**(3)](/gd_move/3.md). To change the name of a field, use [**gd\_rename**(3)](/gd_rename/3.md). 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**). If *field\_code* specifies a **RAW** field 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 *field\_code* specifies a **LINTERP** field and the *recode* argument is non-zero, the look-up table file will be moved if *entry***-\>***table* specifies a different path. If a file with the new pathname already exists, it will be overwritten. If the field specified by *field\_code* is of type other than **RAW** or **LINTERP**, the *recode* argument is ignored. If *field\_code* specified a **LINCOM** or **POLYNOM** field, the value of *entry***-\>***comp\_scal* indicates whether the purely real scalar lists (*entry*-\>*a*, or *entry*-\>*b* and *entry*-\>*m*) or the complex valued lists (*entry*-\>*ca*, or *entry*-\>*cb* and *entry*-\>*cm*) will be used. The unused counterparts need not be initialised. The *entry***-\>***field\_type* member must correspond to the field type of *field\_code*. This interface cannot be used to change the type of a given field. To do so, delete the old field first with [**gd\_delete**(3)](/gd_delete/3.md), and then create a new field of the desired type with [**gd\_add**(3)](/gd_add/3.md). Some entry members have special values which indicate no change should be made to the member. These special values are:\ .TP 8 **NULL:** any of the string members;\ .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 *entry***-\>***scalar* elements relevant for the given field type must be initialised to one of the following values: - • a pointer to a field code indicating a new scalar field to be used for the corresponding field parameter. If the parameter was previously a literal number, it will be replaced by the specified field code. If the parameter was previously a field code, the new field code will replace the old one. If the field code specifies a **CARRAY** field, the corresponding *entry***-\>***scalar\_ind* element should also be set. - • a pointer to the empty string (""). In this case, no change is made to the field code for the corresponding field parameter: if one already existed, it is kept, otherwise the corresponding literal numerical parameter is used. If the value of the corresponding numerical *entry* member is the special value listed above indicating no change, no change is made to the field parameter at all. **NB:** In this case, GetData also ignores the corresponding *entry***-\>***scalar\_ind* element, even if it differs from the current value. To change a *scalar\_ind* element without changing the corresponding *scalar*, set that *scalar* element to its current value (at which point GetData operates as per the previous bullet). - • the NULL pointer. If the corresponding field parameter was previously a field code, the field code will be deleted and a literal number used instead. In the special case when a scalar element is NULL and the corresponding numerical *entry* member contains a special value indicating no change listed above, GetData will de-reference the previous field code value and convert it into a literal number before removing the field code from the entry. If this function 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. ## RETURN VALUE On success, **gd\_alter\_entry**() 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. This error may also result from attempting to dereference a scalar field code which indicates a non-existent field.\ .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\ .TP 8 **GD\_E\_BAD\_ENTRY** One or more of the parameters specified in *entry* was invalid.\ .TP 8 **GD\_E\_BAD\_FIELD\_TYPE** The *entry***-\>***field\_type* parameter did not correspond to the type of the field specified by *field\_code*, or an attempt was made to modify the immutable *INDEX* field. This error may also result from attempting to dereference a scalar field code which does not indicate a **CONST** or **CARRAY** field.\ .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\_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 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 function **dirfile\_alter\_entry**() appeared in GetData-0.5.0. In GetData-0.7.0, this function was renamed to **gd\_alter\_entry**(). In GetData-0.8.0, the first version supporting fragment affixes, this function would apply the destination fragment's affixes to the supplied *entry***-\>***field* name. In GetData-0.8.1, this changed: **gd\_alter\_entry**() now assumes *entry***-\>***field* contains the full field name, including any necessary affixes. In GetData-0.10.0, the error return 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\_alter\_bit**(3)](/gd_alter_bit/3.md), [**gd\_alter\_carray**(3)](/gd_alter_carray/3.md), [**gd\_alter\_const**(3)](/gd_alter_const/3.md), [**gd\_alter\_divide**(3)](/gd_alter_divide/3.md), [**gd\_alter\_lincom**(3)](/gd_alter_lincom/3.md), [**gd\_alter\_linterp**(3)](/gd_alter_linterp/3.md), [**gd\_alter\_multiply**(3)](/gd_alter_multiply/3.md), [**gd\_alter\_phase**(3)](/gd_alter_phase/3.md), [**gd\_alter\_polynom**(3)](/gd_alter_polynom/3.md), [**gd\_alter\_raw**(3)](/gd_alter_raw/3.md), [**gd\_alter\_recip**(3)](/gd_alter_recip/3.md), [**gd\_alter\_spec**(3)](/gd_alter_spec/3.md), [**gd\_delete**(3)](/gd_delete/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_hidden**(3)](/gd_hidden/3.md), [**gd\_malter\_spec**(3)](/gd_malter_spec/3.md), [**gd\_metaflush**(3)](/gd_metaflush/3.md), [**gd\_move**(3)](/gd_move/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_put\_carray\_slice**(3)](/gd_put_carray_slice/3.md), [**gd\_rename**(3)](/gd_rename/3.md), [dirfile-format(5)](/dirfile-format/5.md)