gd_flush(3)

💾 gd_flush(3) — GETDATA 💾

okay bestie so we're doing the GETDATA flush-and-close trio today and honestly?? these three little functions are the ones that make sure your Dirfile actually writes itself down instead of just vibing in RAM like a menace. 🫶

✨ NAME ✨

gd_flush, gd_raw_close, gd_sync — write all pending Dirfile changes to disk, or close open raw fields. basically: save it or shut it. 💅

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_flush(DIRFILE *dirfile, const char *field_code);

int gd_raw_close(DIRFILE *dirfile, const char *field_code);

int gd_sync(DIRFILE *dirfile, const char *field_code);

🦋 DESCRIPTION 🦋

so. gd_sync() is the one that pushes all the pending writes to disk for the raw data files associated with field_code, or with its input(s), in the dirfile that you handed over as dirfile. and if field_code has a valid representation suffix on it?? it gets ignored. like, not today, suffix. 🙈

✨ special case alert ✨ if you pass NULL as field_code to gd_sync(), then every single field in dirfile gets flushed. and in that same special case, modified metadata also gets flushed to disk, exactly as if gd_metaflush(3) had been called. iconique behavior, no notes. 💖

also lowkey important: if the dirfile was opened read-only, this function does literally nothing. and on top of that, some encoding schemes may just implement this whole thing as a NOP. so like… sometimes it's giving nothing on purpose. 😭

gd_raw_close() closes any raw data files that GetData has opened which are associated with field_code, or with its input(s). and again — if field_code is NULL, then all open data files get closed. 📁✂️ and heads up: the I/O pointer of any RAW field that gets closed is reset to the beginning-of-field. so it's not just closing, it's also rewinding, bestie. ⏪

calling gd_flush() is essentially equivalent to calling gd_sync() first and then gd_raw_close() (ie. it does both of those tasks), though if field_code is NULL, the order of operations may be different than making those two explicit calls. so same destination, possibly different route. 🗺️✨

👑 RETURN VALUE 👑

on success, all three of these return zero. slay. on error, a negative-valued error code comes back. possible error codes are:

• GD_E_ALLOC — the library could not allocate memory. it simply did not have the bandwidth. 💀
• GD_E_BAD_CODE — the field specified by field_code was not found in the database. it's not there, girl. 🍓
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 🚩
• GD_E_IO — an I/O error happened while trying to write modified data or metadata to disk. 😭
• 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, that maximum length is at least 2**31 bytes, so if you're seeing this, it typically means something pathological is happening. like genuinely what are you doing. 💀
• GD_E_RECURSE_LEVEL — too many levels of recursion were hit while trying to resolve field_code. this usually means there's a circular dependency in the field specification in the dirfile. 🔁🚨

the error code is also stored in the DIRFILE object, and you can go grab it after this function returns by calling gd_error(3). and if you want a descriptive error string for it, call gd_error_string(3). 🫶

📜 HISTORY 📜

• the dirfile_flush() function appeared in GetData-0.3.0.
• in GetData-0.7.0, this function was renamed to gd_flush().
• the gd_raw_close() and gd_sync() functions appeared in GetData-0.8.0.
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code.

🔗 SEE ALSO 🔗

gd_close(3), gd_dirfile_standards(3), gd_error(3), gd_error_string(3), gd_metaflush(3), gd_open(3)

and that's the whole page, bestie!! this one is Version 0.10.0, dated 25 December 2016, and it's the gd_flush(3) girlies' moment to shine. go flush something. periodt. 💖✨🎀🦋