gd_add_spec(3)

💖 gd_add_spec(3) — GETDATA manual, but make it cute 💖

okay bestie, sit down, hydrate, because we're learning how to add a field to a Dirfile and honestly? it's giving main character energy. this is gd_add_spec(3) from the GETDATA manual, and by the end of this page you're gonna be obsessed. 🦋

✨ NAME ✨

gd_add_spec, gd_madd_spec — add a field to a Dirfile

like. that's it. that's the whole job. but the way they do it?? iconic. 👑

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_add_spec(DIRFILE *dirfile, const char *line, int fragment_index);

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

✨ DESCRIPTION ✨

so. gd_add_spec() takes the field specification line in line and adds the field it describes to the dirfile you passed as dirfile. slay. 💅

gd_madd_spec() is basically the same vibe, except it adds the field as a metafield under the field you name in parent. metafield under a parent field… it's giving nepotism but make it data. 🎀

field specification lines are explained in excruciating (affectionate) detail in dirfile-format(5). and here's a fun little glow-up: since Standards Version 7 (peep dirfile(5)) lets you specify a metafield without using the /META directive, you can also use gd_add_spec() to add metafields — just specify the metafield's full field code. full deets live in dirfile-format(5), go read it, i'll wait. 💜

quick note for the gd_madd_spec() girlies: line should contain only a field specification, and not a /META directive. don't do it. i'm serious. 🙈

if you hand these functions a directive line instead of a field specification line, you get a syntax error. periodt. and these functions never call the registered parser callback function — not even if line has a syntax error in it. they simply do not care to involve your callback. 😭

✨ RETURN VALUE ✨

on success, gd_add_spec() and gd_madd_spec() return zero. cute, clean, no notes. ✨

on error, you get a negative-valued error code. yes, negative. the vibes are bad. possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. you tried to write to something that said "look but don't touch." 🚫
• GD_E_ALLOC — the library was unable to allocate memory. it's not the library's fault, it's just tired. 😮‍💨
• GD_E_BAD_CODE — the parent field code was not found, or was already a metafield. (metafield² is not a thing, bestie.) 💀
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. rip.
• GD_E_BAD_INDEX — the fragment_index argument was out of range. it wandered off the map. 🗺️
• GD_E_FORMAT — a syntax error was encountered in line. grammar police but for data. 🚨
• GD_E_IO — an I/O error occurred while creating an empty binary file to be associated with a newly added RAW field. 😭
• 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. (the parser said "tl;dr" fr fr.) 📏
• 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. hands off, it's guarded. 🛡️
• 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. it simply doesn't speak that language. 🫤
• 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. it knows the language, it just refuses. 💅

the error code is also stored in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3). want a descriptive error string instead of a number? call gd_error_string(3). you're welcome. 🫶

✨ HISTORY ✨

• the functions dirfile_add_spec() and dirfile_madd_spec() appeared in GetData-0.4.0. the origin story. 🌱
• in GetData-0.7.0, these functions were renamed to gd_add_spec() and gd_madd_spec(). glow-up era. ✨
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. character development. 🔥

✨ SEE ALSO ✨

gd_add(3), all the gd_add_<entry-type> functions (e.g., gd_add_bit(3)), gd_error(3), gd_error_string(3), gd_madd(3), all the gd_madd_<entry-type> functions (e.g., gd_madd_bit(3)), gd_metaflush(3), gd_open(3), dirfile-format(5)

go forth and read them all, i believe in you. 🌈

that's the whole page bestie!! this was Version 0.10.0, dated 25 December 2016, and honestly it ate. no cap. go add some fields. 👑💖