NAME¶
gd_dirfile_standards — change or report the current Dirfile Standards
Version for a DirFile
SYNOPSIS¶
#include <getdata.h>
int gd_dirfile_standards(DIRFILE *dirfile, int
version );
DESCRIPTION¶
The
gd_dirfile_standards() version updates the current Standards Version
for the open dirfile
dirfile to the value specified by
version,
if possible, and then reports the current Standards Version. Metadata written
to disk for
dirfile will conform to the current Standards Version.
The Standards Version of the loaded dirfile also affects the operation of
functions which add fields, such as
dirfile_add(3) or
dirfile_add_spec(3); and functions which modify field metadata, such as
dirfile_alter_entry(3) or
dirfile_alter_spec(3). For specific
behaviour see the manual page of the appropriate function.
The
version parameter should be between zero and the value of the symbol
GD_DIRFILE_STANDARDS_VERSION, which is the newest Standards Version
understood by GetData, inclusive or else one of the following special symbols:
- GD_VERSION_EARLIEST
- Specifies the current Standards Version should be set to the earliest
version to which the loaded dirfile conforms.
- GD_VERSION_CURRENT
- Specifies that the current Standards Version should not be changed. In
this case, this function simply reports the current Standards
Version.
- GD_VERSION_LATEST
- Specifies the current Standards Version should be set to the latest
version to which the loaded dirfile conforms.
If the loaded dirfile does not conform to the specified
version, this
function fails, and the current Standards Version is unchanged. If the loaded
dirfile conforms to no known Standards Version, this function will fail
regardless of the value of
version (even if
GD_VERSION_CURRENT
is used).
The caller should not assume that the loaded dirfile conforms to every Standards
Version between the values reported by
GD_VERSION_EARLIEST and
GD_VERSION_LATEST.
RETURN VALUE¶
On success,
gd_dirfile_standards() returns the current Standards Version
of the loaded dirfile, after possibly having been updated by the call. This
will be a number between zero and
GD_DIRFILE_STANDARDS_VERSION
inclusive. On error, -1 is returned and the dirfile error is set to a non-zero
error value, and the current Standards Version is not changed. Possible error
values are:
- GD_E_BAD_DIRFILE
- The supplied dirfile was invalid.
- GD_E_BAD_VERSION
- The loaded dirfile did not conform to the specified version. Or the
dirfile conforms to no known Standards Version.
The dirfile error may be retrieved by calling
gd_error(3). A descriptive
error string for the last error encountered can be obtained from a call to
gd_error_string(3).
NOTES¶
This function only changes the current Standards Version of the loaded dirfile.
It does not update the any format specification fragments on disk to conform
to the specified Standards Version. To do that, use
gd_metaflush(3) or
gd_rewrite_fragment(3).
SEE ALSO¶
gd_open(3),
gd_metaflush(3),
gd_rewrite_fragment(3)