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
.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
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
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)