NAME

       af_saverev, af_newgen, af_setbusy, af_sstate, af_svnum - version control in AtFS

SYNOPSIS

       #include <atfs.h>

       int af_saverev (Af_key *busyAso, Af_key *saveAso, int generation, int storeType)

       int af_newgen (Af_key *aso, Af_key *newAso)

       int af_setbusy (Af_key *busyAso, Af_key *aso, Af_key *prevAso)

       int af_sstate (Af_key *aso, int state)

       int af_svnum (Af_key *aso, int gen, int rev)

       int af_predsucc (Af_key *inAso, int mode, Af_key *outAso)

DESCRIPTION

       af_saverev  makes  a  copy of the ASO identified by busyAso.  This new ASO gets the status
       saved and a version number according to the following scheme:

              The initial revision is numbered by generation number 1 and revision number 0.  All
              other  saved versions get version numbers built from these of their predecessors by
              preserving the generation number and increasing the revision number by 1.

       Usually, versions are added to the most recent generation. This is indicated by giving the
       generation  parameter AF_LASTVERS.  It is also possible to add the new version to an older
       generation, indicated by an explicit generation number. In this case, the  predecessor  of
       the  new version is the most recent version of the named generation and the version number
       is built accordingly.

       The storeType argument says, whether the new version shall be stored as delta (difference)
       to  its  predecessor version or completely.  Valid values are AF_STORE_DELTA (default) and
       AF_STORE_COMPLETE.

       All  attributes  except  version  status  and  version  number  (including  user   defined
       attributes) are inherited from the busy version.  The key of the generated ASO is returned
       in saveAso.  Use af_dropkey to free the allocated memory associated with saveAso.

       Creating a new version in the most recent generation of a history requires  reserving  the
       update  permissions  by  setting  a lock on the most recent version (see af_lock(3)).  For
       adding a new version to an old generation, a version lock on the most  recent  version  of
       the  concerned  generation  is needed.  Subsequent calls of af_saverev for the same object
       history each need a new lock, as the most recent version becomes a new one with every call
       of af_saverev.

       af_newgen  opens  a  new  generation  in a object history.  The last saved version will be
       duplicated. This creates a new ASO, that is numbered by a new generation number (increased
       by  1)  and  the  initial  revision  number  (0).  All  other attributes remain unchanged.
       af_newgen requires a lock (see af_lock(3)) set on the ASO specified by aso.

       With af_setbusy an application can inform AtFS, that the data file of a  busy  version  (a
       busy  versions  data  always  sits in a UNIX file) has been exchanged. This is usually the
       case, after having reinstalled an old version to be basis  for  further  development.  The
       argument  aso  denotes  the  version,  from which the new contents of the busy version was
       taken. busyAso points to the current busy version, if there is any. It may also be omitted
       by  giving  a  NULL  pointer.  af_setbusy  returns  prevAso  the  key  of the version that
       previously was set as origin of the busy version.

       af_sstate sets the state of the identified ASO.  Only state transitions from one state  to
       the next or previous state (according to the list below) are allowed. Possible states are:

       busy    The version is under development and its contents may be changed.

       saved   The version is saved and may be used for later backup.

       proposed
               The  version  has  been submitted for publication by the developer but still needs
               formal approval by a quality  assurance  board  to  become  publicly  visible  and
               accessible in the official database.

       published
               The  version  has passed the formal approval and is now accessible to every member
               of the project. It  is  not  yet  accessed  and  may  therefore  be  withdrawn  if
               necessary.

       accessed
               The  version  has  been  published,  and  is  now  accessed by some members of the
               project.

       frozen  The version may be part of a system configuration that has been  released  to  the
               outside world. This means it must, under no circumstances, be destroyed.

       af_svnum  sets  the version number of the identified ASO to the given generation (gen) and
       revision (rev) number.  The version number of source objects can only be increased  -  the
       version  number of derived objects can be set to any value.  af_svnum requires a lock (see
       af_lock(3)) set on the ASO specified by aso.

       af_predsucc returns the predecessor or successor version of inAso. The result is passed in
       the buffer outAso. The value for the mode parameter may be one of the following

       AF_LOGICAL_SUCC
                 logical  successor AF_LOGICAL_PRED logical predecessor AF_PHYSICAL_SUCC physical
                 successor AF_PHYSICAL_PRED physical predecessor

SEE ALSO

       af_intro (3), af_lock(3)

DIAGNOSTICS

       Upon error, -1 is returned and af_errno is set to the corresponding error number

BUGS

       Due to limitations in the UNIX filesystem, only the creator (author) of a  derived  object
       may save ASOs to a derived object cache.

       Empty files cannot be inserted in a derived object cache.

       The modes AF_LOGICAL_PRED and AF_LOGICAL_SUCC for af_predsucc are not yet impelmented.