gd_desync—check for a change of metadata on disk
int gd_desync(DIRFILE *dirfile, unsigned int flags);
The gd_desync() function determines whether the metadata of the loaded dirfile has become desynchronised from the format specification fragments on disk, due to a third party modifying the Dirfile metadata on disk after GetData opened it. If dirfile has become desynchronised, this function can, optionally, reload the dirfile.
The flags argument influences how the function works. It should be zero or more of the following flags, bitwise or'd together:
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)).
When successful, this function returns zero if the loaded dirfile has not desynchronised, or one if it has. On error, a negative-valued error code is returned, regardless of desynchronisation. Possible error codes are:
Additionally, 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.
The error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). A descriptive error string for the error may be obtained by calling gd_error_string(3).
The current implementation uses file modification times as reported by stat(2) to detect changes. These times have a granularity of, at best, one second. As a result, desynchronisation will not be detected in the case when a fragment is modified, then GetData reads it, then the fragment is modified again, all within one second. The caller may wish to perform its own monitoring using the pathnames returned by gd_fragmentname(3).
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.
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.
fstatat(2), stat(2), gd_cbopen(3), gd_discard(3), gd_error(3), gd_error_string(3), gd_parser_callback(3)