gd_alter_encoding(3)

🎀 gd_alter_encoding — bestie, let's talk binary encodings 💅

okay so real quick, this is a page from the GETDATA manual set, section 3, and it's all about gd_alter_encoding(3) — the function that changes up the binary encoding of your data in a Dirfile. stick with me, it's actually so good 🦋

---

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_alter_encoding(DIRFILE *dirfile, unsigned int encoding, int
       fragment_index, int recode);

---

🌸 DESCRIPTION 🌸

so gd_alter_encoding() sets the binary encoding of the format specification fragment that you point at with fragment_index — and it sets it to whatever encoding you pass in, inside the dirfile(5) database that you handed over as dirfile. 💖

what does "binary encoding of a fragment" even mean tho? it's the encoding of the data living in the binary files that belong to the RAW fields defined in that fragment. and lowkey important: if a fragment has no RAW fields in it, its binary encoding is just… ignored. nothing to encode, nothing to care about 🫶

the encoding argument should be one of these symbols, periodt:

• GD_UNENCODED
• GD_BZIP2_ENCODED
• GD_FLAC_ENCODED
• GD_GZIP_ENCODED
• GD_LZMA_ENCODED
• GD_SLIM_ENCODED
• GD_SIE_ENCODED
• GD_TEXT_ENCODED

and if you wanna know what all those actually mean, go read gd_open(3) and dirfile-encoding(5) — they break down every supported encoding scheme for you. no cap. ✨

now, fragment_index doesn't have to just be a normal valid fragment index. it can also be the special value GD_ALL_FRAGMENTS, which is giving "do the thing to literally every fragment in the database" energy 👑 — it changes the encoding of all of them.

and then there's recode. this one's the main character:

• if recode is non-zero, this call will actually recode the binary data of the affected RAW fields so everything matches up with the new binary encoding. 🎀 but heads up: if the fragment's encoding is encoding insensitive, or if the data type is only one byte in size, no change is made. and 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 left completely untouched. hands off. 🙈

---

💀 RETURN VALUE 💀

when everything goes right, gd_alter_encoding() returns zero. slay. 🌈

when it goes wrong, it returns a negative-valued error code. and here's the full roster of possible error codes, bestie:

• GD_E_ACCMODE — the dirfile you gave was opened read-only. can't change what you can't write, sorry 😭
• GD_E_ALLOC — the library could not allocate memory. it tried, it really did.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_INDEX — the supplied index was out of range.
• GD_E_IO — an I/O error happened while trying to recode a binary file.
• GD_E_PROTECTED — either the metadata of the given format specification fragment was protected from change, or the binary data of the fragment was protected from change and you asked for binary file recoding. protected is protected 💅
• GD_E_UNCLEAN_DB — an error occurred while moving the recoded file into place. as a result, 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 stop any further database corruption, and it should be immediately closed. like, immediately. 🚨
• 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 recoding.

also! the error code gets 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 down, call gd_error_string(3). 🫶

---

🧚 NOTES 🧚

a binary file recoding happens out-of-place. so because of that, you need enough space on the filesystem for the binary files of all RAW fields in the fragment, both before and after the translation. double the storage, double the vibe check. if all fragments get updated by specifying GD_ALL_FRAGMENTS, the recoding happens one fragment at a time. ✨

an error code of GD_E_UNCLEAN_DB means a system error occurred while moving the re-encoded 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 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_encoding() appeared in GetData-0.5.0. og era.
• in GetData-0.7.0, this function was renamed to gd_alter_encoding(). glow-up.
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. more info, more better.

---

🦋 SEE ALSO 🦋

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

---

and that's the whole page, bestie 🥰 this one's from Version 0.10.0, dated 25 December 2016 — go forth and recode responsibly, mwah 💖✨🎀