X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=cprogs%2Fwith-lock-ex.1;h=ce3f87fd1b840f86a584e3727ff18588a5a214d1;hb=78ad6d7c4fcfc77d83649a4082a8dae4359bdbf1;hp=63ac832f3e6a82b4193adc3a6ca58553171533df;hpb=07bcf3ad73b5d4555e58cf4c7a2e94fb66f4cfa5;p=chiark-utils.git

diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1
index 63ac832..ce3f87f 100644
--- a/cprogs/with-lock-ex.1
+++ b/cprogs/with-lock-ex.1
@@ -16,7 +16,7 @@ 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
@@ -56,6 +56,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,6 +123,14 @@ 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
@@ -107,3 +139,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. 
+.SH "SEE ALSO"
+.BR fcntl (2),
+.BR flock (2),
+.BR chmod (2)