gd_error(3)

✨ gd_error(3) ✨

okay so bestie, welcome to the GETDATA corner of the manual — this is gd_error, plus its ride-or-die gd_error_string, and together they're literally just here to tell you what went wrong 💅

🌸 NAME 🌸

gd_error, gd_error_string — report a GetData library error 🫶

🎀 SYNOPSIS 🎀

#include <getdata.h>

int gd_error(const DIRFILE *dirfile);

char *gd_error_string(const DIRFILE *dirfile, char *buffer, size_t
       buflen);

that's it. that's the whole vibe. two little functions and a whole lot of emotional support 😭

🦋 DESCRIPTION 🦋

So like, the way that gd_error() works is: it looks at the most recent GetData library function call that operated on dirfile, and it's like "girl, did that work or not?"

• If that last call succeeded, gd_error() returns GD_E_OK — which equals zero. slay ✨
• If that last call failed, gd_error() returns a negative-valued error code telling you the cause of the failure 💀

and here's the tea: the possible codes vary from function to function. So go check the corresponding manual page of the function that failed to get the full list of possible codes. iykyk 🧚

gd_error_string() is basically the same girl but she's an overachiever — she behaves similarly, but she composes a string describing the error 💖

• If buffer is not NULL, the string gets written to that memory location. At most buflen characters will be written, including the terminating NUL byte.
• If buffer is not large enough to hold the entire string, the string will be truncated — but the truncated string will still be NUL-terminated, because she's polite like that 🎀
• If buffer is NULL, gd_error_string() will allocate a string of sufficient length on the heap. In this case, buflen is ignored 🙈
  • By default, malloc(3) is used to allocate this buffer — but an alternate memory manager may be specified by calling gd_alloc_funcs(3) before calling this function.
  • The caller is responsible for deallocating this string when it is no longer needed. yes bestie, YOU. you free it. 🫶

Now, some functions get ignored by these two, because they always succeed and honestly? good for them:

• gd_alloc_funcs(3)
• gd_error_count(3)
• gd_flags(3)
• gd_free_entry_strings(3)
• gd_mplex_lookback(3)
• gd_parser_callback(3)

Previous gd_error() and gd_error_string() calls are also ignored. no self-referential drama here, we're not doing that today 💅

👑 RETURN VALUE 👑

gd_error() always returns the integer error code of the last library call on the supplied DIRFILE object. always. no exceptions. main character behavior fr fr 🔥

gd_error_string() is a little more complicated, so pay attention bestie:

• If buffer is non-NULL, it returns buffer — unless buflen is less than one, in which case it returns NULL. 💀
• If buffer is NULL, this function returns a newly allocated string of sufficient length which should be deallocated by the caller — or NULL if memory allocation failed 😭

🌈 HISTORY 🌈

storytime, gather round 🧚

• The get_error_string() function appeared in GetData-0.3.0. vintage queen ⭐
• The get_error() function appeared in GetData-0.4.0. Before this, the error code was directly accessible via the dirfile->error member in the DIRFILE structure. like, manually. wild times 😭
• In GetData-0.7.0, these functions were renamed to gd_error() and gd_error_string(). This is also the first release in which gd_error_string() would allocate a buffer for the error string if passed NULL. glow-up era ✨

💜 SEE ALSO 💜

• gd_error_count(3)

go read her too, she's iconic in her own right 🫶

and that's the whole page bestie!! this was Version 0.10.0, dated 25 December 2016, from the GETDATA manual, section 3 — gd_error(3), periodt 💅✨🎀🦋🌸