gd_aliases(3)

🦋 gd_aliases — the manual page, but make it a group chat 🦋

okay bestie, so this one is gd_aliases(3) from the GETDATA manual, and it is genuinely one of my faves because it's so simple and it just works. Sit down, hydrate, let's go 💖

✨ NAME ✨

gd_aliases — retrieve a list of aliases for a field in a Dirfile database

like. that's the whole job. it gives you the aliases. iconic behaviour, no notes 👑

🌸 SYNOPSIS 🌸

#include <getdata.h>

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

look at that. two arguments. clean. minimal. the way that this function doesn't over-explain itself?? we love a low-effort queen 💅

🎀 DESCRIPTION 🎀

So. The gd_aliases() function queries a dirfile(5) database — the one you specify with dirfile — and hands you back a read-only list of aliases of the field you asked for with field_code. That's it, that's the whole vibe. 🫶

Okay but fr fr, there are some rules:

• The dirfile argument must point to a valid DIRFILE object that you already made with a call to gd_open(3). No fake dirfiles, bestie, we can tell. 🙈
• The array that comes back gets de-allocated by a call to gd_close(3) — so do not de-allocate it yourself. Not your array, not your problem, hands off. 💀
• Do not assume the list is in any particular order. It's giving chaos, it's giving shuffle, and that's fine.
• The array is terminated by a NULL pointer. classic.
• Wanna know how many strings are in there? Call gd_naliases(3). She'll tell you. 🌈

⚠️ Genuinely important, no cap: the caller may not modify any strings in the array, or the array itself. Doing so may cause database corruption. Like. Do not touch. We are looking respectfully. 👀

And about that pointer you get back — it's guaranteed to be valid until gd_aliases() is called again with the same arguments, or until the array is de-allocated by a call to gd_close(3). That's the whole warranty. Know it, love it. ✨

🔥 RETURN VALUE 🔥

Upon successful completion, gd_aliases() returns a pointer to an array of strings containing the values of all the aliases for the specified field. The array is terminated by a NULL pointer. And if it's successful, this list will always contain at least one entry, to wit: field_code. (yes she includes herself in her own list. main character energy. we stan. 👑)

On error it returns NULL and sets the dirfile error to a non-zero error value. Possible error values are:

• GD_E_ALLOC — the library was unable to allocate memory. the malloc said no ma'am 😭
• GD_E_BAD_CODE — the specified field code was not found in the database. she's not here, girl, she never was 💀
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. bestie that's not a dirfile, that's a vibe. 🚩

Wanna retrieve the dirfile error? Call gd_error(3). Want a descriptive error string for the last error encountered? That's gd_error_string(3). She'll tell you what went wrong, in words, like a friend. 🧚

💜 HISTORY 💜

The gd_aliases() function appeared in GetData-0.8.0. Baby's first debut, and she ate. 🎀

⭐ SEE ALSO ⭐

gd_open(3), gd_alias_target(3), gd_naliases(3), dirfile(5)

go read those too, iykyk, they're all part of the same little family 🦋

Version 0.10.0 · 25 December 2016 — yeah that's the whole source/version and date situation, and honestly? a lil retro, a lil vintage, we respect the timeline 💖 mwah, go call gd_close(3) when you're done, ily, bye!! ✨🎀🫶