gd_parent_fragment(3)

💖 gd_parent_fragment — it's giving "who's your parent bestie" 💖

okay so real talk, this is gd_parent_fragment(3) from the GETDATA manual, and it's lowkey one of the cutest lil functions in the whole dirfile family. it's short, it's sweet, it answers exactly one question, and it ate. let's get into it 🫶

✨ NAME ✨

gd_parent_fragment — bestie, this retrieves the parent fragment of a fragment in a Dirfile. that's it. that's the whole job. iconic behaviour honestly 🎀

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_parent_fragment(DIRFILE *dirfile, int fragment_index);

like look at that. two args. no drama. we love a function that knows what it is 💅

✨ DESCRIPTION ✨

so the gd_parent_fragment() function queries a dirfile(5) database — the one you specify with dirfile — and hands you back the index of the fragment that contains the INCLUDE directive for the fragment indexed by fragment_index. it's literally just "hey who adopted this fragment" and the function is like "found them, here's their number 💖".

but bestie, listen, there's a plot twist 🌸 the primary format specification fragment is not included in any other fragment. it's the original. the main character. nobody parented it. so if you pass zero for fragment_index, you're asking about the one fragment that has no parent, and it will result in an error. not me asking the orphan about their parents 😭

✨ RETURN VALUE ✨

on success, gd_parent_fragment() returns the index of the specified fragment's parent. slay. correct. no notes ✨

on error, gd_parent_fragment() returns a negative-valued error code. the possible error codes are:

• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. it's giving "this isn't a dirfile, bestie" 💀
• GD_E_BAD_INDEX — the supplied index was out of range, or was equal to zero. (yeah. zero. the primary fragment. we talked about this 🥲)

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 nice lil descriptive error string instead of a raw number? call gd_error_string(3). that's your girl for the gossip 🫶

✨ HISTORY ✨

the lore, because you know I did the research 📚✨

• the get_parent_fragment() function appeared in GetData-0.5.0.
• in GetData-0.7.0, this function was renamed to gd_parent_fragment().
• 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 ✨

dirfile(5), gd_include(3), gd_open(3), gd_fragmentname(3), gd_nfragments(3)

go read those too, they're all part of the same friend group 💜

Version 0.10.0 · 25 December 2016 — that's the source and the date bestie, and this was gd_parent_fragment(3), signing off. stay iconic, go call gd_error_string(3) when things get weird, and remember: not every fragment has a parent and that's okay 🌈💖✨