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

       The flags argument influences how the function works.  It should be zero or more of the following  flags,
       bitwise or'd together:

       GD_DESYNC_PATHCHECK
               Ignore  GetData's internal directory cache, and use the format 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 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

       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  er‐
       ror codes 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 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).

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.

HISTORY

       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.

SEE ALSO

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

Version 0.10.0                                  25 December 2016                                    gd_desync(3)