gd_uninclude(3)

💖 gd_uninclude 💖

okay bestie, welcome to GETDATA section 3, and today's main character is gd_uninclude — the girl whose whole job is removing a format specification fragment from a Dirfile. yes, she's the one who shows up with the trash bag. no cap. 🗑️✨

🌸 NAME 🌸

gd_uninclude — remove a format specification fragment from a Dirfile 🦋

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_uninclude(DIRFILE *dirfile, int fragment_index, int del);

💅 DESCRIPTION 💅

so like, gd_uninclude() takes the format specification fragment at fragment_index out of the dirfile you gave her. and not just that one — she also takes out any fragments that the indicated fragment INCLUDEs. it's giving "you and your whole friend group are uninvited." 💀

any fields defined in the removed fragments? gone. removed from the dirfile. bye. 👋

before she removes anything, all the pending writes get flushed to the RAW fields defined in the fragments she's about to remove. so nothing's left hanging, periodt.

• if del is zero, metadata changes also get written to the removed fragments.
• if del is non-zero, the format specification fragments get deleted from disk, if possible. (key phrase: if possible 🫠)

but listen — regardless of what del is, the binary data files associated with RAW fields defined in the removed fragments are NOT deleted. she will not touch them. absolutely not her job.

if you actually want those binary files gone, call gd_delete(3) before you call this function. that's the move. 🌟

and the big one: the primary format specification (the fragment indexed by zero) cannot be removed from the dirfile. she's the main character. she stays. 👑

🔥 RETURN VALUE 🔥

slay = success = gd_uninclude() returns zero. 😌

if something goes wrong, you get a negative-valued error code. the possible ones are:

• GD_E_ACCMODE — the dirfile you handed her was opened in read-only mode. bestie cannot write. 🙈
• GD_E_ALLOC — the library could not allocate memory. it's giving broke. 💀
• GD_E_BAD_DIRFILE — the dirfile you supplied was invalid.
• GD_E_BAD_INDEX — the fragment index you gave was out of range, or you tried to remove the primary format specification. (we said she can't leave!! 👑)
• GD_E_IO — an I/O error happened while trying to write modified data or metadata to disk.
• GD_E_PROTECTED — the metadata of the fragment that included the removed fragment was protected from change. 🔒

the error code also gets stashed in the DIRFILE object, so you can go get it after this function returns by calling gd_error(3). and if you want an actual descriptive error string? call gd_error_string(3). 🎀

🧚 NOTES 🧚

this function re-arranges the remaining format specification fragments in some unspecified way — except for the primary fragment, which is guaranteed to stay at index zero. she is anchored. ⚓

so if you're a caller who caches format specification fragment indices: re-initialise your cache after calling this function. don't be out here trusting stale indices, i'm begging you. 😭

🌈 HISTORY 🌈

• dirfile_uninclude() appeared in GetData-0.5.0. the og name. vintage. 🕰️
• in GetData-0.7.0, this function was renamed to gd_uninclude().
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up fr fr. ✨

🫶 SEE ALSO 🫶

gd_delete(3), gd_include(3), gd_open(3), gd_error(3), gd_error_string(3), gd_fragmentname(3), gd_nfragments(3), gd_reference(3), dirfile(5), dirfile-encoding(5), dirfile-format(5)

that's the whole page babes 💖 this was Version 0.10.0, dated 25 December 2016 — a lil christmas gift of documentation from the GetData girlies. go forth, uninclude responsibly, and remember: primary fragment stays at index zero, always and forever. periodt. 🎀💅🦋