oracular (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()  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)