NAME

       gd_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 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, re‐
       load the dirfile.

       The flags argument influences how the function works.  It should be zero, or else one or more of the fol‐
       lowing 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 symbol‐
               ic 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 assump‐
               tion 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 er‐
       ror 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.

SEE ALSO

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

Version 0.9.0                                    16 October 2014                                    gd_desync(3)