gd_dirfile_standards(3) 					      GETDATA						   gd_dirfile_standards(3)

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  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  be-
       haviour 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 Ver-
       sion 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  Stan-
	      dards 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_VER-
       SION_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)

Version 0.7.0							  15 October 2010					   gd_dirfile_standards(3)