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 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).

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)