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 sets  the  current  Standards  Version  for  the  open
       dirfile  dirfile  to  the value specified by version, determining the syntax used to write
       metadata to disk for dirfile.

       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 that
               supports all the features of the loaded dirfile;

       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 that
               supports all the features of the loaded dirfile;

               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 non-negative
       integer between zero and GD_DIRFILE_STANDARDS_VERSION inclusive.  On  error,  a  negative-
       valued error code is returned, and the current Standards Version is not changed.  Possible
       error codes 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  error  code  is  also  stored  in  the DIRFILE object and may be retrieved after this
       function returns by calling gd_error(3).  A descriptive error string for the error may  be
       obtained by calling 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).

HISTORY

       The function gd_dirfile_standards() appeared in GetData-0.7.0.

       In  GetData-0.10.0,  the  error  return  from this function changed from -1 to a negative-
       valued error code.

SEE ALSO

       gd_open(3), gd_metaflush(3), gd_rewrite_fragment(3)