gd_rewrite_fragment(3)

💖 gd_rewrite_fragment(3) — GETDATA 💖

okay bestie, pull up a chair, because we're about to talk about gd_rewrite_fragment(3) from the GETDATA manual, and honestly? she's giving "quietly essential". no cap.

✨ NAME ✨

gd_rewrite_fragment — re-write a Dirfile format specification fragment 💅

🦋 SYNOPSIS 🦋

#include <getdata.h>

int gd_rewrite_fragment(DIRFILE *dirfile, int fragment);

🌸 DESCRIPTION 🌸

so here's the tea: gd_rewrite_fragment() writes the format specification fragment you picked — the one named by fragment — straight to disk, and it does this regardless of whether it has changed or not, just straight up overwriting the existing file. no vibe check, no "did u mean to do that", it just goes. 🔥

and plot twist: fragment doesn't have to be a plain old valid fragment index. it can also be the special value GD_ALL_FRAGMENTS, which means "bestie, rewrite every single fragment", periodt.

the metadata gets written to disk using the current Standards Version as stored in the dirfile object. wanna change it or just report it? go see gd_dirfile_standards(3), she handles all of that. and uh — if your dirfile metadata conforms to no known Standards Version at all? yeah, a Standards non-compliant fragment will be written. iconic behaviour, honestly. 💀

👑 RETURN VALUE 👑

slay on success: zero is returned. 😌

on error: a negative-valued error code comes back. the possible error codes are, in order:

• GD_E_ACCMODE — the dirfile you handed over was opened in read-only mode. read-only means read-only, bestie. 🙈
• GD_E_ALLOC — the library could not allocate memory. she tried, the memory said no.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. not it. 🚫
• GD_E_BAD_INDEX — the fragment index you supplied was out of range.
• GD_E_IO — an I/O error happened while trying to write modified 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 indicates something pathological is happening. like, girl, what are you doing. 😭

also! the error code is stored in the DIRFILE object too, so you can grab it after this function returns by calling gd_error(3). and if you want a descriptive error string for whatever went wrong, hit up gd_error_string(3). 🫶

💀 BUGS 💀

when writing metadata using Standards Version 4 or earlier, the reference field may change, owing to the lack of a /REFERENCE directive. the work-around is to upgrade to Standards Version 5 or later. consider this your sign to upgrade, fr fr.

🌈 HISTORY 🌈

• the gd_rewrite_fragment() function appeared in GetData-0.7.0. a whole era. ⭐
• in GetData-0.10.0, the error return from this function 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_flush(3), gd_metaflush(3), gd_open(3)

and that's the whole page, bestie — Version 0.10.0, dated 25 December 2016, from the gd_rewrite_fragment(3) page in the GETDATA manual. go forth and rewrite those fragments responsibly. mwah. 💖✨🧚