nntpid as found in chiark's /usr/local/bin/nntpid.old, apparently copied from a versi...

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

diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1
index f83f263f1ec3a7cd2b651b8467586c3880bca978..941d1d9a0fa3a2d59d8c8aa2baa98ca0de7806ea 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


@@ -21,14 +21,16 @@ for each user class for which the umask has
 .SH OPTIONS
 .TP
 .B \-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


@@ -112,7 +138,7 @@ This Manual page was written by Matthew Vernon <matthew@debian.org>
 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 may be used by anyone.
 .SH COPYRIGHT
 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 may be used by anyone.
 .SH COPYRIGHT

-with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
+with-lock-ex was written by Ian Jackson <ian@chiark.greenend.org.uk>

 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 domain. 
 .SH "SEE ALSO"
 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 domain. 
 .SH "SEE ALSO"