gd_hide(3)

✨ gd_hide(3) — GETDATA manual, bestie edition ✨

okay so you're in the GETDATA section of the manual and you've found gd_hide(3), which is lowkey one of the most useful little gremlins in the whole library. it's giving "i have secrets and i'm keeping them." let's get into it 💅

🌸 NAME 🌸

gd_hide, gd_unhide — hide or unhide a Dirfile database entry

like, invisibility cloak but for your dirfile entries. no cap.

🎀 SYNOPSIS 🎀

#include <getdata.h>

int gd_hide(const DIRFILE *dirfile, const char *entry_name);

int gd_unhide(const DIRFILE *dirfile, const char *entry_name);

two functions, same energy, opposite directions. one hides, one unhides. they're a matched set, your honor. 🫶

🦋 DESCRIPTION 🦋

So gd_hide() takes the field or alias called entry_name in the dirfile(5) database specified by dirfile and hides it, and it also tells you whether the field or alias in question is hidden or not. And gd_unhide()? bestie, it does the exact reverse — it unhides the entry you point at. ✨

Not me also mentioning that you can hide or unhide an entry with gd_alter_entry(3) too. options, we love options. 💖

By default (key words: by default), a hidden entry does not show up in the lists returned by gd_match_entries(3), gd_entry_list(3), gd_constants(3), or gd_strings(3) — and yes, that includes the special-case versions of gd_entry_list(3) like gd_field_list(3). so if you're wondering where your entry went, it's not gone, it's just not invited to the list party 🙈

and the omission is reflected in the counts returned by the corresponding field counting function gd_nentries(3) and its special-case versions (gd_nfields(3), &c.). the number goes down. the entry is still there. it's just hidden. periodt.

🔥 RETURN VALUE 🔥

on a successful completion, gd_hide() and gd_unhide() return zero. slay. on error, they return a negative-valued error code. (negative. bad vibes. we don't like it.)

possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. you're in read-only mode bestie, you literally cannot touch the metadata, i'm so sorry 😭
• GD_E_BAD_CODE — the field specified by field_code was not found in the database. doesn't exist. ghosted you fr fr 💀
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. the whole thing is a mess, not just the entry.
• GD_E_PROTECTED — the metadata of the affected format specification fragments was protected from change. hands off, it's guarded 🔒

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 instead of just a code? call gd_error_string(3). it'll tell you what's wrong in actual words, which is iconic honestly.

👑 HISTORY 👑

gd_hide() and gd_unhide() appeared in GetData-0.8.0. throwback. they've been here a minute. ⭐

and then in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. glow-up behavior. the API said "let me be more specific" and we respect it. 💜

🌈 SEE ALSO 🌈

• gd_alter_entry(3)
• gd_field_list(3)
• gd_hidden(3)
• gd_nfields(3)
• gd_open(3)
• dirfile(5)

iykyk. go read them. they're all part of the same story 🧚

and that's the whole page bestie 💖 this was Version 0.10.0, dated 25 December 2016 — a lil christmas gift from the GetData girlies. stay hidden, stay iconic, and remember: just because it's not in the list doesn't mean it's not there. mwah 🎀💅✨