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

NAME

14       gd_dirfile_standards  —  change or report the current Dirfile Standards
15       Version for a DirFile
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       int gd_dirfile_standards(DIRFILE *dirfile, int version);
22
23

DESCRIPTION

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
29       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
35       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
40       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
45       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
50       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
55               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
61               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
65

RETURN VALUE

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
74       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
78       GD_E_BAD_DIRFILE
79               The supplied dirfile was invalid.
80
81       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
86

NOTES

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
93

HISTORY

95       The function gd_dirfile_standards() appeared in GetData-0.7.0.
96
97       In  GetData-0.10.0, the error return from this function changed from -1
98       to a negative-valued error code.
99
100

SEE ALSO

102       gd_open(3), gd_metaflush(3), gd_rewrite_fragment(3)
103
104
105
106Version 0.10.0                 25 December 2016        gd_dirfile_standards(3)
Impressum