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, reload the dirfile.

       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.

SEE ALSO

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