gd_raw_filename(3)

💖 gd_raw_filename — bestie edition 💖

okay so this is gd_raw_filename(3) from the GETDATA manual, and it's literally the "where does this file even LIVE" function. it hands you the pathname of a binary file inside a Dirfile. that's the whole vibe. let's get into it 🦋

✨ NAME ✨

gd_raw_filename — retrieve the pathname of a binary file in a Dirfile 🗂️✨

🌸 SYNOPSIS 🌸

#include <getdata.h>

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

💅 DESCRIPTION 💅

so the gd_raw_filename() function reports the pathname of the file backing the RAW field that you specified with field_code, inside the dirfile you passed in as dirfile. that's it. it's giving "tell me where this file is at" energy 💁‍♀️

and listen — if field_code happens to contain a valid representation suffix, bestie, it gets ignored. fully ignored. not even a little bit considered. 🫥

👑 RETURN VALUE 👑

on success, gd_raw_filename() returns the full pathname of the binary file associated with the specified field, sitting pretty in a newly-allocated buffer. ✨

by default that buffer is allocated with malloc(3), but you can swap in a different memory manager by calling gd_alloc_funcs(3) before you call this function. and the receipts? the caller is responsible for deallocating the returned buffer. that means YOU, bestie. free it. don't leave it hanging, that's a leak and we don't do that here 💀

on error, this function returns NULL and stores a negative-valued error code in the DIRFILE object, which you can grab with a subsequent call to gd_error(3). possible error codes, and yes we're listing every single one:

• GD_E_ALLOC — the library could not allocate memory. the malloc said no 😭
• GD_E_BAD_CODE — the field specified by field_code was not found. it's not there. it never was. 💀
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. the dirfile itself? fake. 🙈
• GD_E_BAD_FIELD_TYPE — the field specified by field_code was not a RAW field. wrong type, wrong vibe, wrong function. 🚫
• GD_E_UNKNOWN_ENCODING — the encoding scheme of the specified field could not be determined, or it wasn't understood by GetData. it's giving mystery encoding 🔍

and if you want the actual descriptive error string for whatever went wrong, hit up gd_error_string(3). that's the one that actually talks. 🗣️

🧚 HISTORY 🧚

okay so a lil lore drop for you 📜

the get_raw_filename() function appeared in GetData-0.4.2. back then, the memory for the string it returned was managed by GetData. so you didn't have to worry about it. those were the days. 😌

then in GetData-0.7.0, this function got renamed to gd_raw_filename(). glow-up, honestly. ✨

and in GetData-0.8.0, the returned string changed to a malloc'd buffer, and the responsibility for freeing that buffer got passed to the caller. plot twist: now it's your problem 🫠

🌈 SEE ALSO 🌈

• free(3)
• gd_entry(3)
• gd_error(3)
• gd_error_string(3)
• malloc(3)
• dirfile(5)
• dirfile-encoding(5)
• dirfile-format(5)

and that's the whole page, bestie 🎀 this was Version 0.10.0, dated 25 December 2016 — yes, a christmas day release, iconic behavior, whoever shipped that ate and left no crumbs 💅🦋 go free your buffers, ily, bye ✨