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() function 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  ap‐
       propriate 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  spe‐
       cial 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 func‐
       tion 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 val‐
       ues 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_STAN‐
       DARDS_VERSION  inclusive.  On error, -1 is returned and the dirfile error is set to a non-zero error val‐
       ue, 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).

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.8.0                                     29 June 2012                           gd_dirfile_standards(3)