gd_desync(3)

✨ NAME ✨

gd_desync — check for a change of metadata on disk 💖

okay bestie, real talk: this is a getdata manpage, third section, and it's literally all about noticing when someone else has been messing with your dirfile's metadata behind your back. no cap.

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_desync(DIRFILE *dirfile, unsigned int flags);

💅 DESCRIPTION 💅

so the whole vibe of gd_desync() is: it figures out whether the metadata of the loaded dirfile has become desynchronised from the format specification fragments sitting on disk. and like, how would that even happen? 🙈 a third party modifying the Dirfile metadata on disk after GetData opened it. rude, honestly.

and if dirfile has become desynchronised, this function can optionally reload the dirfile for you. slay.

the flags argument is the main character here — it decides how the function does its thing. it should be zero or more of these flags, bitwise or'd together 🫶:

• GD_DESYNC_PATHCHECK — ignore GetData's internal directory cache and use the format fragments' full path when checking for modifications. this one is highkey important when the dirfilename passed to gd_cbopen(3), or directory paths used in included fragments, contain symbolic links: with this flag, those symbolic links get re-evaluated. without it, the target of the symbolic links in effect when the dirfile was first opened is what gets considered instead. iykyk ✨
• GD_DESYNC_REOPEN — if this flag is specified and gd_desync() detects desynchronisation, the Dirfile gets re-opened in place using the existing dirfile pointer. and in that case, upon a positive result from this function, the caller must discard all cached information about the dirfile — even the assumption that dirfile has been successfully opened. not me being dramatic, that's just the rules 💀

re-opening the dirfile is equivalent to calling gd_discard(3), and then gd_cbopen(3) with the same arguments used when originally creating dirfile, except that the dirfile pointer doesn't change its value. as a result, this function may invoke the registered parser callback function (see gd_cbopen(3) and gd_parser_callback(3)). 🎀

🎀 RETURN VALUE 🎀

when it's all going well, this function returns zero if the loaded dirfile has not desynchronised, or one if it has.

on error though? it returns a negative-valued error code, regardless of desynchronisation. the possible error codes are:

• GD_E_ALLOC — the library was unable to allocate memory. 😭
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 🚩
• GD_E_IO — an error occurred while trying to obtain the modification time of a fragment.

also, if GD_DESYNC_REOPEN is used, this function may fail for any of the reasons listed in the gd_discard(3) and gd_cbopen(3) manual pages. so many ways to go wrong, lowkey iconic.

the error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). and a descriptive error string for the error? get that by calling gd_error_string(3). 💜

🦋 LIMITATIONS 🦋

okay so here's the tea, and it's important tea ☕

the current implementation uses file modification times as reported by stat(2) to detect changes. and those times have a granularity of, at best, one second. so as a result, desynchronisation will not be detected in this exact case: a fragment is modified, then GetData reads it, then the fragment is modified again — all within one second. 😬 yeah. sneaky.

the caller may wish to perform its own monitoring using the pathnames returned by gd_fragmentname(3). just saying. 👑

on systems lacking a POSIX.1-2008 conformant fstatat(2) (q.v.), this function may always operate as if GD_DESYNC_PATHCHECK had been specified, regardless of the actual flags. so like, the flag might just be doing its own thing. 🙈

👑 HISTORY 👑

• the function gd_desync() appeared in GetData-0.8.0. ✨
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up fr fr.

🌈 SEE ALSO 🌈

fstatat(2), stat(2), gd_cbopen(3), gd_discard(3), gd_error(3), gd_error_string(3), gd_parser_callback(3)

and that's the whole page bestie, no notes 🫶 this was Version 0.10.0, dated 25 December 2016, straight out of the GETDATA manual — mwah, periodt 💅🌸