SYNOPSIS
#include <getdata.h>- int gd_dirfile_standards(DIRFILE *dirfile, int version);
DESCRIPTION
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_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 descriptive error string for the last error encountered can be obtained from a call to gd_error_string(3).