1gd_dirfile_standards(3) GETDATA gd_dirfile_standards(3)
10
14 gd_dirfile_standards — change or report the current Dirfile Standards
15 Version for a DirFile
16
19 #include <getdata.h>
20 int gd_dirfile_standards(DIRFILE *dirfile, int version);
22
25 The gd_dirfile_standards() function sets the current Standards Version
26 for the open dirfile dirfile to the value specified by version, deter‐
27 mining the syntax used to write metadata to disk for dirfile.
28 The Standards Version of the loaded dirfile also affects the operation
30 of functions which add fields, such as dirfile_add(3) or
31 dirfile_add_spec(3); and functions which modify field metadata, such as
32 dirfile_alter_entry(3) or dirfile_alter_spec(3). For specific behav‐
33 iour see the manual page of the appropriate function.
34 The version parameter should be between zero and the value of the sym‐
36 bol GD_DIRFILE_STANDARDS_VERSION, which is the newest Standards Version
37 understood by GetData, inclusive, or else one of the following special
38 symbols:
39 GD_VERSION_EARLIEST
41 Specifies the current Standards Version should be set to the
42 earliest version that supports all the features of the loaded
43 dirfile;
44 GD_VERSION_CURRENT
46 Specifies that the current Standards Version should not be
47 changed. In this case, this function simply reports the cur‐
48 rent Standards Version;
49 GD_VERSION_LATEST
51 Specifies the current Standards Version should be set to the
52 latest version that supports all the features of the loaded
53 dirfile;
54 If the loaded dirfile does not conform to the specified
56 version, this function fails, and the current Standards Version
57 is unchanged. If the loaded dirfile conforms to no known Stan‐
58 dards Version, this function will fail regardless of the value
59 of version (even if GD_VERSION_CURRENT is used).
60 The caller should not assume that the loaded dirfile conforms
62 to every Standards Version between the values reported by
63 GD_VERSION_EARLIEST and GD_VERSION_LATEST.
64
67 On success, gd_dirfile_standards() returns the current Standards Ver‐
68 sion of the loaded dirfile, after possibly having been updated by the
69 call. This will be a non-negative integer between zero and
70 GD_DIRFILE_STANDARDS_VERSION inclusive. On error, a negative-valued
71 error code is returned, and the current Standards Version is not
72 changed. Possible error codes are:
73 GD_E_ARGUMENT
75 The loaded dirfile did not conform to the specified version.
76 Or the dirfile conforms to no known Standards Version.
77 GD_E_BAD_DIRFILE
79 The supplied dirfile was invalid.
80 The error code is also stored in the DIRFILE object and may be re‐
82 trieved after this function returns by calling gd_error(3). A descrip‐
83 tive error string for the error may be obtained by calling
84 gd_error_string(3).
85
88 This function only changes the current Standards Version of the loaded
89 dirfile. It does not update the any format specification fragments on
90 disk to conform to the specified Standards Version. To do that, use
91 gd_metaflush(3) or gd_rewrite_fragment(3).
92
95 The function gd_dirfile_standards() appeared in GetData-0.7.0.
96 In GetData-0.10.0, the error return from this function changed from -1
98 to a negative-valued error code.
99
102 gd_open(3), gd_metaflush(3), gd_rewrite_fragment(3)
103Version 0.10.0 25 December 2016 gd_dirfile_standards(3)