gd_dirfile_standards(3) GETDATA gd_dirfile_standards(3)NAMEgd_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() function updates the current Standards Ver‐
sion 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 Ver‐
sion.
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 behav‐
iour see the manual page of the appropriate function.
The version parameter should be between zero and the value of the sym‐
bol 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_CUR‐
RENT 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 Ver‐
sion of the loaded dirfile, after possibly having been updated by the
call. This will be a number between zero and GD_DIRFILE_STANDARDS_VER‐
SION 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_ARGUMENT
The loaded dirfile did not conform to the specified version.
Or the dirfile conforms to no known Standards Version.
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive 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 ALSOgd_open(3), gd_metaflush(3), gd_rewrite_fragment(3)Version 0.8.0 29 June 2012 gd_dirfile_standards(3)
