gd_invalid_dirfile(3)

💅 gd_invalid_dirfile — the GETDATA manual, bestie edition 💅

okay so real quick, this page lives in the GETDATA manual, and it's all about gd_invalid_dirfile(3). yes that's the whole vibe. let's go ✨

✨ NAME ✨

gd_invalid_dirfile — obtain an pointer to an invalid DIRFILE object 🫶

(yes the original says "an pointer". we do not fix the original. we respect the original. periodt.)

🌸 SYNOPSIS 🌸

#include <getdata.h>

DIRFILE* gd_invalid_dirfile(void);

like, that's it. no arguments. she takes nothing and she gives you a DIRFILE*. iconic 💅

🦋 DESCRIPTION 🦋

so bestie, gd_invalid_dirfile() hands you back a pointer to a newly allocated, invalid DIRFILE object. like, she's real, she exists in memory, she's just… not valid. it's giving "made it five minutes ago and already has no purpose" 😭

but here's the thing — even though she's invalid, she's still a DIRFILE object like any other, which means you still gotta de-allocate her when you're done. you do that by calling gd_close(3) or gd_discard(3). no leaving her hanging, that's rude fr fr.

now. the DIRFILE object you get back? you can pass it to any other GetData function that wants one. nobody's stopping you. but doing so will inevitably make that function fail with the GD_BAD_DIRFILE error. like, every single time. it's not a "maybe". it's not a "sometimes". it's inevitable. the way that this object has one job and that job is being rejected 💀

🎀 you could also just… do this instead 🎀

ngl there's a similar effect you can get by making a bad gd_open(3) call, for example:

gd_open("", 0);

that also returns a pointer to an invalid DIRFILE object! so like, same energy. BUT. and this is the important part — the difference is:

• an invalid DIRFILE created that way has a non-zero error code, which you can get with gd_error(3).
• meanwhile, the dirfile error of the invalid DIRFILE returned by gd_invalid_dirfile(3) is zero, which indicates success.

so like. same object energy, completely different error situation. iykyk 🤫

🔥 RETURN VALUE 🔥

this function always returns a pointer to a newly allocated, invalid DIRFILE object.

…except when it can't allocate memory for the DIRFILE. in that case it returns NULL. that's the one and only exception, bestie. if you get NULL, it's not a vibe, it's a memory problem 🙈

👑 HISTORY 👑

the gd_invalid_dirfile() function first appeared in GetData-0.7.0. a legend was born. ✨

⭐ SEE ALSO ⭐

• gd_close(3)
• gd_discard(3)
• gd_error(3)
• gd_open(3)

go read those too, they're all part of the same little friend group 🫶

Version 0.10.0 🌸 25 December 2016 — that's the version and date this page is serving, and honestly? a christmas-day release is main character energy. slay, gd_invalid_dirfile(3). we love a lowkey useless-but-well-documented function. 💖🎀🦋