1gd_desync(3) GETDATA gd_desync(3)
10
14 gd_desync — check for a change of metadata on disk
15
18 #include <getdata.h>
19 int gd_desync(DIRFILE *dirfile, unsigned int flags);
21
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 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 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 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 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
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 GD_E_ALLOC
66 The library was unable to allocate memory.
67 GD_E_BAD_DIRFILE
69 The supplied dirfile was invalid.
70 GD_E_IO An error occurred while trying to obtain the modification time
72 of a fragment.
73 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 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
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 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
99 The function gd_desync() appeared in GetData-0.8.0.
100 In GetData-0.10.0, the error return from this function changed from -1
102 to a negative-valued error code.
103
106 fstatat(2), stat(2), gd_cbopen(3), gd_discard(3), gd_error(3),
107 gd_error_string(3), gd_parser_callback(3)
108Version 0.10.0 25 December 2016 gd_desync(3)