@@ -1,3 +1,9 @@

[chiark-utils.git] / cprogs / with-lock-ex.1

diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1
index 63ac832f3e6a82b4193adc3a6ca58553171533df..3715cd8a76b503b2ba81464e1d2362c78582d578 100644 (file)
--- a/cprogs/with-lock-ex.1
+++ b/cprogs/with-lock-ex.1
@@ -3,7 +3,7 @@
 with-lock-ex \- file locker
 .SH SYNOPSIS
 .B with-lock-ex
 with-lock-ex \- file locker
 .SH SYNOPSIS
 .B with-lock-ex

-.RB [\| \-w \||\| \-q \||\| \-f \|]
+.BR \-w \||\| \-q \||\| \-f

 .I lockfile command 
 .IR args \ \|.\|.\|.
 .br
 .I lockfile command 
 .IR args \ \|.\|.\|.
 .br


@@ -16,19 +16,21 @@ unlocked automatically by the kernel.
 .PP
 If the file does not exist it is created, with permissions
 .B rw
 .PP
 If the file does not exist it is created, with permissions
 .B rw

-for each user class for which the default umask has
+for each user class for which the umask has

 .BR w .
 .SH OPTIONS
 .TP
 .B \-w
 .BR w .
 .SH OPTIONS
 .TP
 .B \-w

-wait for the lock
+Wait for the lock to be available.

 .TP
 .B \-f
 .TP
 .B \-f

-fail if the lock cannot be acquired
+Fail (printing a message to stderr and exiting 255) if the lock cannot
+be acquired immediately because another process has it.

 .TP
 .B \-q
 .TP
 .B \-q

-silently do nothing (ie, exit 0 instead of executing the specified
-process) if the lock cannot be acquired
+Silently do nothing (ie, exit 0 instead of executing the specified
+process) if the lock cannot be acquired immediately because another
+process has it.

 .SH STALE LOCKS
 The locking protocol used does not suffer from stale locks.  If the
 lock cannot be acquired, one or more running processes must currently
 .SH STALE LOCKS
 The locking protocol used does not suffer from stale locks.  If the
 lock cannot be acquired, one or more running processes must currently


@@ -56,6 +58,30 @@ which a process might lock simultaneously, either
 or
 .IR B > A
 where the relation > is transitive and noncyclic.
 or
 .IR B > A
 where the relation > is transitive and noncyclic.

+.PP
+Then, for any two locks
+.I X
+and
+.I Y
+with
+.IR X > Y
+it is forbidden to acquire
+.I X
+while holding
+.IR Y .
+Instead, acquire
+.I X
+first, or release
+.I Y
+before (re)acquiring
+.I X
+and
+.I Y
+in that order.
+.PP
+(There are more complicated ways of avoiding deadlocks, but a lock
+hierarchy is simple to understand and implement.  If it does not meet
+your needs, consult the literature.)

 .SH LOCKING PROTOCOL
 The locking protocol used by
 .B with-lock-ex
 .SH LOCKING PROTOCOL
 The locking protocol used by
 .B with-lock-ex


@@ -99,6 +125,14 @@ and deleted the file in the meantime; you must now close your
 filedescriptor and start again.
 .B with-lock-ex
 follows this specification.
 filedescriptor and start again.
 .B with-lock-ex
 follows this specification.

+.PP
+Note that
+.BR flock (2)
+is a different kind of lock to
+.BR fcntl (2).
+.B with-lock-ex
+uses
+.BR fcntl .

 .SH AUTHOR
 This Manual page was written by Matthew Vernon <matthew@debian.org>
 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 .SH AUTHOR
 This Manual page was written by Matthew Vernon <matthew@debian.org>
 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but


@@ -107,3 +141,7 @@ may be used by anyone.
 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 domain. 
 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 domain. 

+.SH "SEE ALSO"
+.BR fcntl (2),
+.BR flock (2),
+.BR chmod (2)