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.