gd_alter_entry(3)

💖 gd_alter_entry — bestie edition 💖

okay so picture this: it's a getdata man page, it's a GETDATA manual page, and it's called gd_alter_entry. she's a 3 (library function, iykyk). and she's here to change up the metadata of a Dirfile field. no cap. 💅

---

✨ NAME ✨

gd_alter_entry — modify the metadata of a Dirfile field 🎀

---

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const
       gd_entry_t *entry, int recode);

---

🦋 DESCRIPTION 🦋

okay so the tea is: gd_alter_entry() takes the field you name in field_code inside the dirfile you name in dirfile and glow-ups it to match the new parameters you're passing in entry. 💖

and listen — field_code isn't just regular fields. she can also point at a metafield, as long as you spell it out with its full (slashed) field code. BUT. and this is important bestie: field_code should never contain a representation suffix. never ever. 🚫

the shape of entry is explained in excruciating gorgeous detail over in the get_entry(3) man page. here's the thing though — entry->field and entry->fragment_index are ignored by this function, so you literally don't even have to initialise them, they're just vibing. every other member that's appropriate to the field type of field_code should be initialised, except for the special cases noted down below. 👇

want to change the fragment index of a field? that's a gd_move(3) situation. want to change the name of a field? take it to gd_rename(3). this girl doesn't do that. 🙅‍♀️

🎀 the flags situation 🎀

the only flags in the entry->flags member that get honoured are:

• GD_EN_HIDDEN — set it or clear it to set the hiddenness of the entry (peep gd_hidden(3) for that one)
• GD_EN_COMPSCAL — tells you whether scalar parameters are initialised from the complex valued member or the purely real member, and both of those are present for LINCOM, POLYNOM, and RECIP

🔥 the recode lore 🔥

if field_code specifies a RAW field and recode is non-zero, the binary file hanging out with that field gets converted for changes in data type and samples-per-frame. and when that happens, the field's I/O pointer gets reset to the beginning-of-frame. (main character behaviour, honestly.) if recode is zero, no binary file conversion happens at all. zero. nada. 🧊

if field_code specifies a LINTERP field and recode is non-zero, the look-up table file gets moved if entry->table specifies a different path.

⚠️ if a file with the new pathname already exists, it will be overwritten. not a drill. 😭

if the field specified by field_code is any type other than RAW or LINTERP, then recode is just... ignored. it's giving background character. 💀

💜 the LINCOM / POLYNOM scalars 💜

if field_code specifies a LINCOM or POLYNOM field, the value of entry->comp_scal decides which list gets used:

• the purely real scalar lists — entry->a, or entry->b and entry->m
• the complex valued lists — entry->ca, or entry->cb and entry->cm

and the unused counterparts? they don't need to be initialised at all. they can stay in bed. 🛌

⭐ field types are NOT up for negotiation ⭐

entry->field_type must correspond to the field type of field_code. periodt. this interface cannot be used to change the type of a given field. nope.

if you really want a different type, the routine is:

1. delete the old field first with gd_delete(3)
2. then create a new field of the desired type with gd_add(3)

🌈 special "no change" values 🌈

some entry members have special values that mean "don't touch this, leave it alone". they are:

• NULL — any of the string members
• 0 — spf, n_fields, numbits, cdividend, dividend, or array_len
• -1 — bitnum or period
• GD_NULL — data_type or const_type
• GD_WINDOP_UNK — windop

🫶 the scalar element rules 🫶

every entry->scalar element that's relevant for the given field type must be initialised to one of these:

• 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 gets replaced by the specified field code. if the parameter was previously a field code, the new field code replaces the old one. and 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's kept, otherwise the corresponding literal numerical parameter is used. and if the value of the corresponding numerical entry member is one of those special no-change values listed up there, then 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. so if you want to change a scalar_ind element without changing the corresponding scalar, set that scalar element to its current value — at which point GetData operates like the previous bullet. 😌
• the NULL pointer. if the corresponding field parameter was previously a field code, the field code gets deleted and a literal number is used instead. in the special case where a scalar element is NULL and the corresponding numerical entry member contains one of those special no-change values, GetData will de-reference the previous field code value and convert it into a literal number before removing the field code from the entry. iconic, honestly. 👑

🍓 one last carray thing 🍓

if you use this function to increase the length of a CARRAY field, the added elements will be uninitialised. they're just born like that. use gd_put_carray_slice(3) or an equivalent to initialise them. 🧚

---

💅 RETURN VALUE 💅

on success, gd_alter_entry() returns zero. 🎉 on error, a negative-valued error code is returned. the possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. rude.
• GD_E_ALLOC — the library was unable to allocate memory. 😭
• GD_E_BAD_CODE — the field specified by field_code was not found, or a supplied field code didn't 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.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_ENTRY — one or more of the parameters specified in entry was invalid.
• 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.
• 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.
• 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.
• 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. 🛡️
• 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. (yes, that sentence really does say "be associated", we're keeping it exactly as it is 💀)
• 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 you can retrieve it after this function returns by calling gd_error(3). want a descriptive error string instead? that's gd_error_string(3). 🫶

---

🌸 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 that changed: gd_alter_entry() now assumes entry->field contains the full field name, including any necessary affixes. growth. 💖

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

see gd_entry(3) for the history of the gd_entry_t structure. 📜

---

👑 SEE ALSO 👑

gd_alter_bit(3), gd_alter_carray(3), gd_alter_const(3), gd_alter_divide(3), gd_alter_lincom(3), gd_alter_linterp(3), gd_alter_multiply(3), gd_alter_phase(3), gd_alter_polynom(3), gd_alter_raw(3), gd_alter_recip(3), gd_alter_spec(3), gd_delete(3), gd_error(3), gd_error_string(3), gd_hidden(3), gd_malter_spec(3), gd_metaflush(3), gd_move(3), gd_open(3), gd_put_carray_slice(3), gd_rename(3), dirfile-format(5)

---

and that's the whole page bestie!! 🎀 this was Version 0.10.0, dated 25 December 2016, from the gd_alter_entry(3) page in the GetData manual. merry christmas to those who celebrate, and happy metadata-altering to those who don't. mwah 💋✨🌈