1
2
3
4
5
6
7
8
9gd_desync(3)                        GETDATA                       gd_desync(3)
10
11
12

NAME

14       gd_desync — check for a change of metadata on disk
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_desync(DIRFILE *dirfile, unsigned int flags);
21
22

DESCRIPTION

24       The  gd_desync() function determines whether the metadata of the loaded
25       dirfile has become desynchronised from the format  specification  frag‐
26       ments  on  disk, due to a third party modifying the Dirfile metadata on
27       disk after GetData opened it.  If dirfile  has  become  desynchronised,
28       this function can, optionally, reload the dirfile.
29
30       The flags argument influences how the function works.  It should be ze‐
31       ro or more of the following flags, bitwise or'd together:
32
33       GD_DESYNC_PATHCHECK
34               Ignore GetData's internal directory cache, and use  the  format
35               fragments'  full  path  when  checking for modifications.  This
36               flag is of particular importance when the dirfilename passed to
37               gd_cbopen(3),  or  directory  paths used in included fragments,
38               contain symbolic links: with this flag,  these  symbolic  links
39               will  be  re-evaluated.  Without it, the target of the symbolic
40               links in effect when the dirfile was first opened will be  con‐
41               sidered instead.
42
43       GD_DESYNC_REOPEN
44               If this flag is specified, and gd_desync() detects desynchroni‐
45               sation, the Dirfile will be re-opened in place using the  exit‐
46               ing dirfile pointer.  In this case, upon a positive result from
47               this function, the caller must discard all  cached  information
48               about  the  dirfile,  even the assumption that dirfile has been
49               successfully opened.
50
51               Re-opening the dirfile is equivalent to calling  gd_discard(3),
52               and  then gd_cbopen(3) with the same arguments used when origi‐
53               nally creating dirfile, except that the dirfile pointer doesn't
54               change  its  value.   As a result, this function may invoke the
55               registered  parser  callback  function  (see  gd_cbopen(3)  and
56               gd_parser_callback(3)).
57
58

RETURN VALUE

60       When  successful,  this function returns zero if the loaded dirfile has
61       not desynchronised, or one if it has.  On error, a negative-valued  er‐
62       ror  code is returned, regardless of desynchronisation.  Possible error
63       codes are:
64
65       GD_E_ALLOC
66               The library was unable to allocate memory.
67
68       GD_E_BAD_DIRFILE
69               The supplied dirfile was invalid.
70
71       GD_E_IO An error occurred while trying to obtain the modification  time
72               of a fragment.
73
74       Additionally,  if  GD_DESYNC_REOPEN is used, this function may fail for
75       any of the reasons listed in the gd_discard(3) and gd_cbopen(3)  manual
76       pages.
77
78       The  error  code  is  also  stored in the DIRFILE object and may be re‐
79       trieved after this function returns by calling gd_error(3).  A descrip‐
80       tive   error   string   for  the  error  may  be  obtained  by  calling
81       gd_error_string(3).
82
83

LIMITATIONS

85       The current implementation uses file modification times as reported  by
86       stat(2) to detect changes.  These times have a granularity of, at best,
87       one second.  As a result, desynchronisation will not be detected in the
88       case when a fragment is modified, then GetData reads it, then the frag‐
89       ment is modified again, all within one second.  The caller may wish  to
90       perform   its   own   monitoring   using   the  pathnames  returned  by
91       gd_fragmentname(3).
92
93       On systems lacking a POSIX.1-2008 conformant  fstatat(2)  (q.v.),  this
94       function  may  always operate as if GD_DESYNC_PATHCHECK had been speci‐
95       fied, regardless of the actual flags.
96
97

HISTORY

99       The function gd_desync() appeared in GetData-0.8.0.
100
101       In GetData-0.10.0, the error return from this function changed from  -1
102       to a negative-valued error code.
103
104

SEE ALSO

106       fstatat(2),    stat(2),   gd_cbopen(3),   gd_discard(3),   gd_error(3),
107       gd_error_string(3), gd_parser_callback(3)
108
109
110
111Version 0.10.0                 25 December 2016                   gd_desync(3)
Impressum