gd_alter_spec(3)

✨ gd_alter_spec ✨

okay bestie, this is the gd_alter_spec(3) page from the GETDATA manual, and it's giving "let me change my mind about this field" energy. come sit, we're gonna read it together 💖

🌸 NAME 🌸

gd_alter_spec, gd_malter_spec — modify a field in a Dirfile

🦋 SYNOPSIS 🦋

#include <getdata.h>

int gd_alter_spec(DIRFILE *dirfile, const char *line, int recode);

int gd_malter_spec(DIRFILE *dirfile, const char *line, const char
       *parent, int recode);

💅 DESCRIPTION 💅

so. gd_alter_spec() takes the field described by the field specification line in line and modifies it, in the dirfile that dirfile points at. iconic behavior, honestly.

gd_malter_spec() is basically the same girl but with a plot twist: it modifies the metafield under the field indicated by the field code parent. also, field specification lines are described in detail in dirfile-format(5), so if you need the lore, that's where it lives 📖

The name of the field you're modifying must already exist, and it gets pulled straight out of the field specification line. heads up: when you're adding a metafield, line should only contain a field specification — do not put a /META directive in there. not the vibe. 🙈

If the field you modified is of type RAW and the recode argument is non-zero, the binary file associated with the field gets converted for changes in data type and samples-per-frame. when that happens, the field's I/O pointer gets reset to the beginning-of-frame. (yes, we're rewinding. main character reset moment.) if recode is zero, no binary file conversion happens at all, periodt.

If the modified field is of type LINTERP and recode is non-zero, the look-up table file will be moved if line specifies a different path — and it will overwrite an existing file with the new pathname, if present. so, like, be aware 👀 if the field specified by field_code is of type other than RAW or LINTERP, then recode is just ignored entirely. it's not even being looked at. it's fine.

⚠️ real talk: if you pass these functions a directive line instead of a field specification line, you get a syntax error. full stop. and these functions never call the registered parser callback function — not even if line contains a syntax error. so don't count on that callback to save you, bestie, it's not coming.

⭐ RETURN VALUE ⭐

On success, gd_alter_spec() and gd_malter_spec() return zero. 🎉 On error, it returns a negative-valued error code. Possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. (can't touch this, literally.)
• GD_E_ALLOC — the library was unable to allocate memory. 😭
• GD_E_BAD_CODE — the field specified in line was not found, or the parent field code was not found.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_FORMAT — a syntax error was encountered in line.
• 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_LINE_TOO_LONG — the supplied line was longer than the parser was able to deal with. line lengths are limited by the storage size of size_t.
• 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.
• GD_E_UNSUPPORTED — the encoding scheme of the indicated format specification fragment does not support translating the empty 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? call gd_error_string(3). 🫶

🌈 HISTORY 🌈

The functions dirfile_alter_spec() and dirfile_malter_spec() appeared in GetData-0.5.0. throwback era.

In GetData-0.7.0, these functions were renamed to gd_alter_spec() and gd_malter_spec.() — glow-up arc complete ✨

In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. glow-up part two.

👑 SEE ALSO 👑

Any of the gd_alter_<entry-type> functions (e.g., gd_alter_bit(3)), gd_alter_spec(3), gd_error(3), gd_error_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5)

Version 0.10.0 — 25 December 2016 🎀 that's the version and the date, bestie, noted and archived. this has been gd_alter_spec(3), go forth and modify responsibly 💜