gd_close(3)

💖 gd_close(3) 💖

part of the GETDATA manual, bestie 💅

okay so listen. this is the page about gd_close() and gd_discard() — the two functions that close a Dirfile and free associated memory. it's giving cleanup era. it's giving ✨closure✨ (literally).

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_close(DIRFILE *dirfile);

int gd_discard(DIRFILE *dirfile);

🦋 DESCRIPTION 🦋

so gd_close() and gd_discard() both try to close the open Dirfile dirfile and free all the memory that's associated with it. no cap, all of it. 🧹

the difference between them? okay so gd_close() first flushes all pending metadata updates to disk. that whole step? gd_discard() skips it entirely and simply discards metadata changes. yeah. it said "not me saving that" 💀.

but wait — for dirfiles opened read-only, these two functions are equivalent. so if you're in read-only mode, pick either one, it's the same vibe. periodt.

next up: all pending data gets flushed to disk and all open data files get closed. and here's the plot twist — in order to make sure that modified data files associated with RAW fields are properly terminated, changes to RAW data files are still flushed to disk by gd_discard(). so like, it discards metadata but it does NOT discard your RAW data. that's a whole different thing. 🙈

finally, if the above didn't hit an error, these functions free the memory associated with the DIRFILE object. bye bestie 🫶

if dirfile is NULL, nothing happens, and the call succeeds. iconic behaviour, honestly. no drama.

⚠️ okay this part is important: one of these functions should be called on all pointers returned by gd_cbopen(3), gd_open(3), and gd_invalid_dirfile(3) — even if the call to those function failed. yes, even then. and after gd_close() or gd_discard() returns successfully, the pointer dirfile should be considered invalid. do not touch it. it's gone. it's in its past lives era. 💀

metadata is written to disk using the current Standards Version as stored in the dirfile object. wanna change or report the current Standards Version? see gd_dirfile_standards(3). and if the dirfile metadata conforms to no known Standards Version, then Standards non-compliant metadata will be written. so like. it'll just write it anyway. bold of it but okay. 😭

✨ RETURN VALUE ✨

gd_close() and gd_discard() return zero on success. slay. 🎀

on error, they do not de-allocate dirfile and instead return a negative-valued error code. possible error codes are:

• GD_E_ALLOC — the library was unable to allocate memory. it's out of spoons. 😭
• GD_E_LINE_TOO_LONG — while attempting to flush modified metadata to disk, a field specification line exceeded the maximum allowed length. on most platforms, the maximum length is at least 2**31 bytes, so this typically indicates something pathological happening. like girl what are you doing. 💀
• GD_E_IO — an I/O error occurred while trying to write modified data or metadata to disk. in this case, another call to gd_close() or gd_discard() may be attempted. so it's giving "try again bestie, we believe in you". 🫶

the error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). and a descriptive error string for the error may be obtained by calling gd_error_string(3). very demure, very mindful, very informative. 💅

👑 HISTORY 👑

• the function dirfile_close() appeared in GetData-0.3.0.
• the function dirfile_discard() appeared in GetData-0.6.0.
• in GetData-0.7.0 these functions were renamed to gd_close() and gd_discard(). rebrand era ✨
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. glow up fr fr.

🌈 SEE ALSO 🌈

• gd_dirfile_standards(3)
• gd_error(3)
• gd_error_string(3)
• gd_flush(3)
• gd_invalid_dirfile(3)
• gd_open(3)

and that's the whole page, bestie. this was Version 0.10.0, dated 25 December 2016 — yeah it's a lil vintage, but so is everything good. go close your dirfiles. free your memory. hydrate. 💖🦋✨