NAME

       af_lock, af_unlock, af_testlock - mechanism for reserving update rights in AtFS

SYNOPSIS

       #include <atfs.h>

       Af_user *af_lock (Af_key *aso, Af_user *locker)

       Af_user *af_unlock (Af_key *aso)

       Af_user *af_testlock (Af_key *aso)

DESCRIPTION

       This  manual  page  describes  the  interface  to  the  AtFS  locking  mechanism. Locks are used to avoid
       conflicting updates to one object history. After a user has reserved the update rights, no other user may
       add new versions to the reserved history.  Reserving the update rights happens by locking the most recent
       version of the history.  As AtFS allows adding new  versions  to  each  generation  in  a  history,  each
       generation may be locked separately. Reserving update rights for old generations (with generation numbers
       smaller than the newest generation) are performed by locking the most recent version of the corresponding
       generation.   Removing  an  ASO  (af_rm  -  manual page af_files(3)) and changing an ASO's version number
       (af_svnum - manual page af_version(3)) also requires a lock on the corresponding ASO.

       af_lock reserves the update permission for the user identified by locker.  On  successful  completion,  a
       buffer identical to locker is returned, a NULL pointer otherwise.

       af_unlock cancels a formerly established reservation of update rights. Only the owner or the locker of an
       ASO (identified by the Af_user structure that was given to the corresponding call of af_lock) are allowed
       to  do  this.  On  successful completion, af_unlock returns a buffer containing the identification of the
       former locker. This may be empty, if the ASO was not locked.  Upon error, a NULL pointer is returned.

       af_testlock returns a buffer containing an identification of the current locker of the specified ASO.  It
       returns an empty buffer, if no lock is set.

SEE ALSO

       af_version(3), af_files(3)

DIAGNOSTICS

       af_lock and af_unlock return -1 on error and af_errno is set to indicate the error number.