gd_desync(3) GETDATA gd_desync(3)NAMEgd_desync — check for a change of metadata on disk
SYNOPSIS
#include <getdata.h>
int gd_desync(DIRFILE *dirfile, unsigned int flags);
DESCRIPTION
The gd_desync() function reports whether the metadata of the loaded
dirfile has become desynchronised from the format specification frag‐
ments 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 ze‐
ro, or else one or more of the following flags, bitwise or'd together:
GD_DESYNC_PATHCHECK
Ignore GetData's internal directory cache, and use the format
specification fragments' full path when checking for modifica‐
tions. This flag is of particular importance when the dirfile‐
name passed to gd_cbopen(3), or directory paths used in includ‐
ed fragments, contain symbolic links: with this flag, these
symbolic links will be re-evaluated. Without it, the target of
the symbolic links in effect when the dirfile was first opened
will be considered instead.
GD_DESYNC_REOPEN
If this flag is specified, and gd_desync() detects desynchroni‐
sation, the Dirfile will be re-opened in place using the exit‐
ing dirfile pointer. In this 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.
Re-opening the dirfile is equivalent to calling gd_discard(3),
and then gd_cbopen(3) with the same arguments used when origi‐
nally 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
On successful deletion, zero is returned if the loaded dirfile has not
desynchronised, or 1 if it has. On error, -1 is returned, regardless
of desynchronisation and the dirfile error is set to a non-zero error
value. Possible error values are:
GD_E_ALLOC
The library was unable to allocate memory.
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
GD_E_RAW_IO
An error occurred while trying to obtain the modification time
of a fragment.
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 dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
LIMITATIONS
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 frag‐
ment is modified again, all within one second. The caller may wish to
perform its own monitoring using the pathnames returned by gd_fragment‐
name(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 speci‐
fied, regardless of the actual flags.
SEE ALSOfstatat(2), gd_cbopen(3), gd_discard(3), gd_error(3), gd_er‐
ror_string(3), gd_parser_callback(3)Version 0.8.0 15 March 2012 gd_desync(3)
