gd_get_string(3)

💖 gd_get_string — bestie edition 💖

okay so this is a page from the GETDATA manual (section 3, the library calls section, iykyk) and it's all about gd_get_string, which pulls STRING or SARRAY data out of a Dirfile database. no cap. let's get into it 🫶

✨ NAME ✨

gd_get_string — retrieve STRING or SARRAY data from a Dirfile database

✨ SYNOPSIS ✨

#include <getdata.h>

size_t gd_get_string(DIRFILE *dirfile, const char *field_code, size_t
       len, char *data_out);

like. the whole vibe in one function signature. gorgeous. 💅

✨ DESCRIPTION ✨

so gd_get_string() goes and queries a dirfile(5) database — the one you point at with dirfile — looking for the string scalar field_code, and listen: that field code should not have a representation suffix on it. just the plain name, bestie. 🌸

the first len characters of that string scalar get dropped into the user-supplied buffer data_out. and if field_code actually refers to a SARRAY field? you get the first element. that's it. that's the tea. ☕

the dirfile argument has to point to a valid DIRFILE object that you already made by calling gd_open(3). like, a real one. not a fake one. 🙈

now here's the part where it gets spicy 🌶️ — if len equals zero, or if data_out equals NULL, then literally nothing gets copied into data_out, but gd_get_string() will still hand you back the length of the string scalar. so you can use it as a little measuring tape, periodt. otherwise, data_out has to point to a valid memory location that's big enough to hold at least len characters. and if the string scalar is longer than len? data_out will not be NUL-terminated. 😭 not a vibe. know that.

also quick note: the gd_get_sarray(3) function is another way to grab STRING data, but without you needing to know the length in advance. so this whole thing:

size_t len = gd_get_string(dirfile, field_code, 0, NULL);
char *string = malloc(len);
gd_get_string(dirfile, field_code, len, string);

which is doing the absolute most to make sure the whole string comes back, terminating NUL included — can be replaced with just this:

const char *string;
gd_get_sarray(dirfile, field_code, &string);

and the added benefit?? you don't have to manage the memory for the string. no malloc, no cleanup, no stress. iconic behavior honestly. 👑

✨ RETURN VALUE ✨

on success, gd_get_string() returns the actual length of the specified string scalar, including the space for that trailing NUL character. so if the return value is greater than len, that's your signal that the output string is not NUL-terminated. noted. written down. in my notes app. 📝

on error, this function returns 0 and stashes a negative-valued error code inside the DIRFILE object, which you can grab later with gd_error(3). the possible error codes are:

• GD_E_BAD_CODE — the field specified by field_code was not found in the database. it's not there. it never was. 💀
• GD_E_BAD_DIRFILE — an invalid dirfile was supplied. you handed it something cursed.
• GD_E_BAD_FIELD_TYPE — the field_code you gave referred to a field of some type that is not STRING and not SARRAY. wrong department, bestie. 🙅
• GD_E_INTERNAL_ERROR — an internal error happened in the library while it was trying to do the task. this means there's a bug in the library. please report the incident to the maintainer. (yes, really. tell them. 🫶)

and if you want a descriptive error string for whatever went wrong, just call gd_error_string(3). it'll explain it to you nicely. 🌈

✨ HISTORY ✨

• the get_string() function first appeared in GetData-0.4.0. a legend was born. ⭐
• then in GetData-0.7.0, it got renamed to gd_get_string(). glow-up era. ✨

✨ SEE ALSO ✨

gd_get_sarray(3), gd_error(3), gd_error_string(3), gd_open(3), gd_put_string(3), dirfile(5)

bestie this is version 0.10.0, dated 25 December 2016 — happy holidays from the GETDATA crew 🎀 go read the other pages, they're all in the same section 3 and they're lowkey slay 💜 🦋