gd_verbose_prefix(3)

💖 gd_verbose_prefix — the GetData error-message-glow-up page 💖

okay bestie, this is the manual page for gd_verbose_prefix(3), living over in the GETDATA manual. it's short, it's sweet, it's giving "tiny function, big personality". let's go ✨

🌸 NAME 🌸

gd_verbose_prefix — set the prefix on error messages printed by GetData

🎀 SYNOPSIS 🎀

#include <getdata.h>

int gd_verbose_prefix(DIRFILE *dirfile, const char *prefix);

✨ DESCRIPTION ✨

okay so gd_verbose_prefix() sets the prefix that gets printed before error messages output by the GetData library, for the dirfile(5) database you're pointing at with dirfile. 💅

and listen — if prefix is NULL, the current prefix (if there even is one) gets deleted, and no new prefix is saved. bye bye prefix 🫶

now here's the tea, and it's important: GetData only prints error messages for a given Dirfile if it was opened along with the GD_VERBOSE flag, or if that flag got set on the dirfile afterwards using gd_flags(3). if that flag is not set? this function still updates the prefix, but GetData does not use it. so it's just... sitting there. being decorative. 💀

if GD_VERBOSE is set, then when the library encounters an error, it prints:

1. the supplied prefix (if any),
2. followed immediately by the error message (which is the message returned by gd_error_string(3)),
3. followed by a newline.

all of that output goes to the caller's standard error (stderr(3)). 🔥

and the dirfile argument must point to a valid DIRFILE object that was previously created by a call to gd_open(3). no rogue unopened dirfiles, bestie, that's not the vibe.

👑 RETURN VALUE 👑

upon successful completion, gd_verbose_prefix() returns zero. slay. ✨

on error, it returns a negative-valued error code. possible error codes are:

• GD_E_ALLOC — the library was unable to allocate memory. 😭

the error code is also stored in the DIRFILE object, and you can retrieve it after this function returns by calling gd_error(3). want a descriptive error string for the error? that's gd_error_string(3). 🩷

🦋 HISTORY 🦋

the gd_verbose_prefix() function appeared in GetData-0.8.0. a whole icon from way back. 🌈

in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up era. 💅

💜 SEE ALSO 💜

• gd_error(3)
• gd_error_string(3)
• gd_flags(3)
• gd_open(3)
• stderr(3)
• dirfile(5)

ok that's the whole page bestie, no notes 💖

and for the sign-off: this page is Version 0.10.0, dated 25 December 2016 — a lil Christmas gift from the GetData girlies 🎁🧚 periodt.