gd_alter_frameoffset(3)

💖 gd_alter_frameoffset — bestie we're editing the manual page for this one 💖

okay so this is gd_alter_frameoffset(3), from the GETDATA manual, and it is exactly what it sounds like: it moves where your frames start. strap in 🎀

---

✨ NAME ✨

gd_alter_frameoffset — change the starting frame of fields in a Dirfile. that's it. that's the whole job. 💅

---

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_alter_frameoffset(DIRFILE *dirfile, off_t offset, int
       fragment_index, int recode);

---

🦋 DESCRIPTION 🦋

so gd_alter_frameoffset() sets the frame offset of the format specification fragment given by fragment_index to offset, inside the dirfile(5) database that dirfile points at. ✨

and what even is a frame offset? bestie. it's the frame number of the first sample of data stored in the binary files that belong to the RAW fields defined in that specified fragment. that's the vibe. if a fragment has no RAW fields in it, its frame offset is just… ignored, like a text you never answered. 🙈

⚠️ the frame offset may not be negative. periodt.

the dirfile argument has to point to a valid DIRFILE object that you already made by calling gd_open(3). no shortcut, no vibes-based dirfile. 🫶

now, fragment_index can be a plain old valid fragment index, sure. but it can also be the special value GD_ALL_FRAGMENTS, which basically says do this to literally every fragment in the database. main character energy tbh. 👑

and here's the part that actually matters, the recode argument:

• if recode is non-zero, this call will shift the binary data of the affected RAW fields to account for the new frame offset.
  • if the new frame offset is larger than the old one → that means permanent deletion of data from the database. 😭 gone. not coming back. fr fr.
  • if the new frame offset is smaller than the old one → the binary file gets padded at the front with zeroes. cute little zero padding, slay.
  • either way, the I/O pointer of all affected RAW fields gets reset to the beginning-of-frame. ✨
• if recode is zero, the affected binary files are just left completely untouched. no notes. 💅

---

💜 RETURN VALUE 💜

on a successful completion, gd_alter_frameoffset() returns zero. on error, it returns a negative-valued error code. and here's the whole roster of possible error codes, no skipping:

• GD_E_ACCMODE — the specified dirfile was opened read-only. rude of it honestly.
• GD_E_ALLOC — the library couldn't allocate memory. 😭
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. not a real one, bestie.
• GD_E_BAD_INDEX — the supplied index was out of range.
• GD_E_IO — an I/O error happened while trying to shift a binary file.
• GD_E_PROTECTED — the metadata of the given format specification fragment was protected from change, or the binary data of the fragment was protected from change and binary file shifting was requested.
• GD_E_RANGE — the supplied offset was less than zero. we said no negative offsets!!
• GD_E_UNCLEAN_DB — an error occurred while moving the shifted file into place, so the database may be in an unclean state. see the NOTES section below for recovery instructions. in this case the dirfile gets flagged as invalid, to prevent further database corruption, and it should be immediately closed. like, drop everything and close it. 🚨
• GD_E_UNKNOWN_ENCODING — the encoding scheme of the fragment is unknown.
• GD_E_UNSUPPORTED — the encoding scheme of the fragment does not support binary file shifting. 💀

the error code also gets stored in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3). want a descriptive error string instead? call gd_error_string(3). 🎀

---

🌈 NOTES 🌈

a binary file shift happens out-of-place. so because of that, you need sufficient space on the filesystem for the binary files of all RAW fields in the fragment — both before and after the translation. it's giving "bring two outfits". 🧳✨

and if you're updating all fragments by specifying GD_ALL_FRAGMENTS, the shifting happens one fragment at a time. no multitasking, she does it in order.

⚠️ an error code of GD_E_UNCLEAN_DB means a system error occurred while moving the shifted binary data into place, or while deleting the old data. if that happens, the database may be left in an unclean state. the caller should check the filesystem directly to figure out the actual state of the dirfile data before continuing. for recovery instructions, see the file /usr/share/doc/getdata/unclean_database_recovery.txt. 🫶

---

🎀 HISTORY 🎀

• the function dirfile_alter_frameoffset() appeared in GetData-0.5.0. iconic debut.
• in GetData-0.7.0, this function was renamed to gd_alter_frameoffset(). rebrand era.
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow up. ✨

---

👑 SEE ALSO 👑

gd_open(3), gd_error(3), gd_error_string(3), gd_frameoffset(3), dirfile(5), dirfile-format(5)

---

and that's the whole page bestie 💖 this was Version 0.10.0, dated 25 December 2016 — happy holidays from the GetData girlies, mwah 🎀✨🦋