gd_add_alias(3)

💖 gd_add_alias(3) — GETDATA 💖

okay bestie, pull up a chair, we're talking about gd_add_alias(3) and its sibling gd_madd_alias(3) — the getdata girls whose whole thing is adding fields to a Dirfile. lowkey iconic. this is section 3 of the manual, the GETDATA girlies' home turf, so let's get into it 🎀

✨ NAME ✨

gd_add_alias, gd_madd_alias — add a field to a Dirfile. no cap, that's the whole job description. 💅

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_add_alias(DIRFILE *dirfile, const char *alias_name, const char
       *target_code, int fragment_index);

int gd_madd_alias(DIRFILE *dirfile, const char *parent, const char
       *alias_name, const char *target_code);

like yes, the line breaks are unhinged, that's just how C headers do. copy them exactly, don't @ me 🦋

💜 DESCRIPTION 💜

so. gd_add_alias() adds the alias named alias_name pointing to target_code, and it drops it into the fragment indexed by fragment_index, inside the dirfile that dirfile points at. that's it, that's the vibe. ✨

then we have gd_madd_alias(), which is giving same energy, different placement — it behaves similarly, EXCEPT it adds the field as a meta-entry under the field indicated by the field code parent. so it's a little nested situation, a field living rent-free inside another field's metadata. main character behaviour honestly. 👑

🔥 RETURN VALUE 🔥

on success? zero. we love a clean zero. 🎉

on error? a negative-valued error code comes back at you, and bestie, here's the full roster of possible ones:

• GD_E_ACCMODE — the specified dirfile was opened read-only. so like… you can look but you cannot touch. 💀
• GD_E_ALLOC — the library could not allocate memory. it's not you, it's the heap.
• GD_E_BAD_CODE — either alias_name was invalid (containing an invalid character, or lacking the containing fragment's namespace or affixes), OR the parent field code was not found, or it was already a metafield. messy either way.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. not a real dirfile, just a vibe. 🫠
• GD_E_BAD_INDEX — the fragment_index specified was out of range. she's not here, hun.
• GD_E_DUPLICATE — the alias_name parameter duplicated that of an already existing entry. name already taken, try again 💅
• 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 protected!! 🚫

and yes, the error code is ALSO stored in the DIRFILE object, so after this function returns you can go retrieve it with gd_error(3). want a descriptive error string instead? that's gd_error_string(3). 🫶

⭐ HISTORY ⭐

• gd_add_alias() and gd_madd_alias() appeared in GetData-0.8.0. little babies, all grown up now 🥹
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. glow-up fr fr ✨

🌈 SEE ALSO 🌈

gd_add(3), gd_alias_target(3), gd_entry(3), gd_madd(3), gd_metaflush(3), gd_open(3), dirfile-format(5) — go read your sisters, bestie, they ate 💖

and that's the page!! this is Version 0.10.0, dated 25 December 2016 — a lil christmas gift from the GETDATA girlies to you 🎁✨ slay, periodt, go add some aliases responsibly 👑💅🦋