SYNOPSIS
#include <getdata.h>- int gd_desync(DIRFILE *dirfile, unsigned int flags);
DESCRIPTION
The flags argument influences how the function works. It should be zero, 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 modifications. This flag is of particular importance when the dirfilename passed to gd_cbopen(3), or directory paths used in included 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 desynchronisation, the Dirfile will be re-opened in place using the
exiting
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 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
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_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 descriptive 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 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.