.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: af_lock.3[7.0] Fri Jun 25 14:33:11 1993 andy@cs.tu-berlin.de frozen $
..
.TH af_lock 3 "Fri Jun 25 14:33:11 1993" "AtFS-1.71" "Attribute Filesystem (AtFS)"
.SH NAME
af_lock, af_unlock, af_testlock \- mechanism for reserving update
rights in AtFS
.SH SYNOPSIS
#include <atfs.h>
.sp
Af_user *af_lock (Af_key *aso, Af_user *locker)
.sp
Af_user *af_unlock (Af_key *aso)
.sp
Af_user *af_testlock (Af_key *aso)
.sp
.SH 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 \fImost recent
version\fP 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.
.LP
\fIaf_lock\fP reserves the update permission for the user identified
by \fIlocker\fP. On successful completion, a buffer identical to
locker is returned, a NULL pointer otherwise.
.LP
\fIaf_unlock\fP 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.
.LP
\fIaf_testlock\fP returns a buffer containing an identification of the
current locker of the specified ASO. It returns an empty buffer, if no
lock is set.
.SH SEE ALSO
af_version(3), af_files(3)
.SH DIAGNOSTICS
af_lock and af_unlock return \-1 on error and \fIaf_errno\fP
is set to indicate the error number.