gd_dirfile_standards(3)

💖 gd_dirfile_standards — bestie's guide to the Dirfile Standards Version 💖

okay so this is a page from the GETDATA manual, section 3, and honestly? it's giving "tiny function, big consequences". let's get into it 🦋

🌸 NAME 🌸

gd_dirfile_standards — change or report the current Dirfile Standards Version for a DirFile. that's it. that's the whole job. but the way it does it? iconic.

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_dirfile_standards(DIRFILE *dirfile, int version);

👑 DESCRIPTION 👑

so gd_dirfile_standards() sets the current Standards Version for the open dirfile dirfile to whatever you pass in version, and like... that determines the syntax used to write metadata to disk for that dirfile. it's literally choosing which dialect of dirfile-speak you're writing in. no cap. 💅

and it's not just about disk output either, because the Standards Version of the loaded dirfile also affects the operation of:

• functions that add fields, like dirfile_add(3) or dirfile_add_spec(3)
• functions that modify field metadata, like dirfile_alter_entry(3) or dirfile_alter_spec(3)

for the specific behaviour of any of those, go read that function's own manual page — the deets live there, iykyk.

🎀 what can version be?

the version parameter should be between zero and the value of the symbol GD_DIRFILE_STANDARDS_VERSION, inclusive — and that symbol is the newest Standards Version understood by GetData. OR you can pass one of these special symbols instead, which are also serving looks:

• GD_VERSION_EARLIEST — says the current Standards Version should be set to the earliest version that supports all the features of the loaded dirfile.
• GD_VERSION_CURRENT — says the current Standards Version should not be changed. in this case, this function is simply reporting the current Standards Version. it's just here to gossip, not to edit. 🫶
• GD_VERSION_LATEST — says the current Standards Version should be set to the latest version that supports all the features of the loaded dirfile.

🚨 okay important stuff, listen up: If the loaded dirfile does not conform to the specified version, this function fails, and the current Standards Version is unchanged. and if the loaded dirfile conforms to no known Standards Version, this function will fail regardless of the value of version — even if you used GD_VERSION_CURRENT. 😭 Also, the caller should not assume that the loaded dirfile conforms to every Standards Version between the values reported by GD_VERSION_EARLIEST and GD_VERSION_LATEST. those are endpoints, not a promise about everything in between. fr fr.

⭐ RETURN VALUE ⭐

on success, gd_dirfile_standards() returns the current Standards Version of the loaded dirfile, after possibly having been updated by the call. so yes, you get the glow-up version if there was one. ✨

that return is a non-negative integer between zero and GD_DIRFILE_STANDARDS_VERSION inclusive.

on error, a negative-valued error code is returned, and the current Standards Version is not changed. the possible error codes are:

• GD_E_ARGUMENT — the loaded dirfile did not conform to the specified version. or, the dirfile conforms to no known Standards Version.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 💀

the error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). and if you want a descriptive error string for the error, call gd_error_string(3). she will tell you exactly what went wrong, in words.

🌈 NOTES 🌈

this function only changes the current Standards Version of the loaded dirfile. it does not update any format specification fragments on disk to conform to the specified Standards Version. not me being a vibe-setter but not a renovator 💅

to actually do that on-disk update, use gd_metaflush(3) or gd_rewrite_fragment(3). those are the ones who show up with the tools. 🔥

🦋 HISTORY 🦋

• the function gd_dirfile_standards() appeared in GetData-0.7.0.
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code.

glow-up confirmed. main character evolution. 👑

🧚 SEE ALSO 🧚

gd_open(3), gd_metaflush(3), gd_rewrite_fragment(3)

Version 0.10.0 · 25 December 2016 — that's the version and date this page is serving, bestie, so if you're citing her, cite her right. mwah 💖🎀✨