gd_metaflush(3)

💾 gd_metaflush(3) — GETDATA's lil metadata-saver

okay bestie, gather round, because this one is lowkey the "save ur work before u close the tab" function of the dirfile world. it lives in the GETDATA section of the manual (section 3, the library-call girlies), and its whole job is saving ur edits to disk 🫶

✨ NAME ✨

gd_metaflush — write modified Dirfile metadata to disk 💅

so basically: u changed ur metadata, and now u wanna make it permanent. this is her.

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_metaflush(DIRFILE *dirfile);

one include, one function, one pointer to a dirfile. that's the whole vibe. ✨

🦋 DESCRIPTION 🦋

okay so gd_metaflush() takes all the pending metadata changes in the dirfile u passed in as dirfile, and flushes them to disk. like, actually writes them. no cap.

how does she do it? by re-writing the format specification fragments that contain modified metadata — just straight up overwriting the existing files. and here's the cute part: format file fragments that are unchanged? she does not touch them. not even a little. respect the untouched ones. 👑

metadata gets written to disk using the current Standards Version as stored in the dirfile object. wanna change it or just peek at what it currently is? go call gd_dirfile_standards(3), she's got u. and if the dirfile metadata conforms to no known Standards Version? then a Standards non-compliant fragment gets written. it's giving "no thoughts, just vibes" but for spec compliance 💀

⚠️ heads up bestie: this function flushes only metadata. if u ALSO want the field data flushed, call gd_sync(3) instead. don't be out here expecting data-flushing from a metadata function. that's not her job. 🙈

🎀 RETURN VALUE 🎀

on success? zero. iconic. perfect. no notes. ✨

on error? a negative-valued error code comes back at u. possible codes, alphabetically served:

• GD_E_ACCMODE — the supplied dirfile was opened in read-only mode. girl, u can't write to something u opened read-only. that's just facts. 😭
• GD_E_ALLOC — the library couldn't allocate memory. malloc said no. 💀
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. it's not a dirfile, bestie, it's a mystery. 🕵️
• GD_E_IO — an I/O error happened while trying to write the modified metadata to disk. the disk said "not today." 🔥
• GD_E_LINE_TOO_LONG — while attempting to flush modified metadata to disk, a field specification line exceeded the maximum allowed length. and listen, on most platforms the maximum length is at least 2**31 bytes, so if u hit this, something pathological is happening. like genuinely concerning behavior. 🚩

the error code also gets stored in the DIRFILE object, so u can grab it after this function returns by calling gd_error(3). and if u want an actual human-readable description of what went wrong, gd_error_string(3) has u covered. 🫶

💜 NOTES 💜

when writing metadata using Standards Version 4 or earlier, the reference field may change — this is because those versions lack a /REFERENCE directive. it's not a bug, it's a limitation, but it IS annoying. the work-around? upgrade to Standards Version 5 or later. periodt. 👑

🌈 HISTORY 🌈

a lil lore drop for u, because I know u love context:

• the dirfile_metaflush() function appeared in GetData-0.4.0. baby's first appearance. 🎀
• in GetData-0.7.0, this function was renamed to gd_metaflush(). glow-up era. ✨
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. more info per error, we love to see it. 💅

👑 SEE ALSO 👑

go read these too, bestie, they're all in the family:

gd_close(3), gd_dirfile_standards(3), gd_error(3), gd_error_string(3), gd_open(3), gd_rewrite_fragment(3), gd_sync(3)

and that's the whole page, no cap. this one's from Version 0.10.0, dated 25 December 2016 — a lil holiday-season gift from the GETDATA girlies. mwah 💖 go flush ur metadata, bestie, u got this. 🦋✨