changelog: Document -t option

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

diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1
index 63ac832f3e6a82b4193adc3a6ca58553171533df..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
-.RB [\| \-w \||\| \-q \||\| \-f \|]
+.BR \-w \||\| \-q \||\| \-f
 .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
-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
-wait for the lock
+Wait for the lock to be available.
 .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
-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
@@ -56,6 +58,30 @@ which a process might lock simultaneously, either
 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
@@ -99,11 +125,23 @@ and deleted the file in the meantime; you must now close your
 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
 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"
+.BR fcntl (2),
+.BR flock (2),
+.BR chmod (2)