gd_reference(3)

💖 gd_reference — getdata's little reference-field handler 💖

okay so bestie, you know how every dirfile has that one field it points at? yeah. this is the function that gets it or sets it. it's gd_reference(3) from the GETDATA manual, and it's lowkey iconic. let's go ✨

🎀 NAME 🎀

gd_reference — retrieve or set the reference field for a Dirfile 💅

🦋 SYNOPSIS 🦋

#include <getdata.h>

const char *gd_reference(DIRFILE *dirfile, const char *field_code);

🌸 DESCRIPTION 🌸

so the way that gd_reference() works is: it sets or retrieves the reference field (peep dirfile(5) for the lore on what that even is) that's associated with the dirfile you handed it in dirfile.

here's the vibe check on field_code:

• if field_code is non-NULL 👉 the reference field for the dirfile gets set to the field you specified.
• if field_code is NULL 👉 nothing happens to the reference field, it just stays as it was. no touchy. 🙈

also important, bestie: the field code should refer to a RAW field, and it may not contain a representation suffix. that's the rule. periodt.

✨ RETURN VALUE ✨

when it slays: gd_reference() returns the field code of the dirfile's reference field — which will literally be field_code, if field_code is non-NULL. makes sense, it ate.

but wait 🫶 if there are no RAW fields defined in the dirfile, this function returns NULL, and it does that without raising an error. that's not a fail, that's just how it is. no drama.

on error though 😭 NULL is returned and the dirfile error gets set to a non-zero error value. the possible error values are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. can't touch this. 💀
• GD_E_ALLOC — the library was unable to allocate memory. it's giving out of RAM.
• GD_E_BAD_CODE — the field specified by field_code was not found. nowhere to be found, ghosted. 👻
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. invalid dirfile era.
• GD_E_BAD_FIELD_TYPE — the field specified by field_code was not a RAW field. wrong type, wrong vibe. 🚫
• GD_E_PROTECTED — the metadata of the primary format specification fragment (the file named format in the root dirfile directory) was protected from change. hands off, it's protected. 🔒

you can grab the dirfile error by calling gd_error(3). and if you want a descriptive error string for the last error encountered, that's a gd_error_string(3) call, babes. 💜

🌈 HISTORY 🌈

storytime, because this function has lore:

• the get_reference() function appeared in GetData-0.4.2. it took only one parameter (the DIRFILE), and returned the current reference field. minimalist queen.
• the dirfile_reference() function appeared in GetData-0.5.0. glow up.
• in GetData-0.7.0, the dirfile_reference() function was renamed to gd_reference() and the get_reference() function was removed. rebrand era, and honestly? it was for the best. 👑

⭐ SEE ALSO ⭐

gd_error(3), gd_error_string(3), gd_metaflush(3), gd_open(3), dirfile(5), dirfile-format(5)

go read them, iykyk 🧚

okay that's the whole page!! this was Version 0.10.0, dated 25 December 2016, and it's a gd_reference(3) situation from the GETDATA manual. merry christmas to everyone who celebrates 🎄✨ mwah, go set your reference field bestie 💖🫶