trusty (3) gd_dirfile_standards.3.gz

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