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, reload 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  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

       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 error 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)