NAME¶
with-lock-ex - file locker
SYNOPSIS¶
with-lock-ex -w|
-q|
-f lockfile command
args ...
DESCRIPTION¶
with-lock-ex will open and lock the lockfile for writing and then feed the
remainder of its arguments to
exec(2); when that process terminates the
fd will be closed and the file unlocked automatically by the kernel.
If the file does not exist it is created, with permissions
rw for each
user class for which the umask has
w.
OPTIONS¶
- -w
- Wait for the lock to be available.
- -f
- Fail (printing a message to stderr and exiting 255) if the lock cannot be
acquired immediately because another process has it.
- -q
- Silently do nothing (ie, exit 0 instead of executing the specified
process) if the lock cannot be acquired immediately because another
process has it.
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 hold the lock; if
the lock needs to be freed those processes should be killed.
Under no circumstances should `stale lock cleaner' cron jobs, or the like, be
instituted. In systems where a great many locks may exist, old lockfiles may
be removed from cron but only if each lock is acquired before the lockfile is
removed, for example with
- with-lock-ex -q lockfile rm lockfile
DEADLOCKS¶
There is no deadlock detection. In a system with several locks, a lock hierarchy
should be established, such that for every pair of locks
A and
B
which a process might lock simultaneously, either
A>
B or
B>
A where the relation > is transitive and noncyclic.
Then, for any two locks
X and
Y with
X>
Y it is
forbidden to acquire
X while holding
Y. Instead, acquire
X first, or release
Y before (re)acquiring
X and
Y
in that order.
(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.)
LOCKING PROTOCOL¶
The locking protocol used by
with-lock-ex is as follows:
The lock is held by a process (or group of processes) which holds an fcntl
exclusive lock on the first byte of the plain file which has the specified
name. A holder of the lock (and only a holder of the lock) may delete the file
or change the inode to which the name refers, and as soon as it does so it
ceases to hold the lock.
Any process may create the file if it does not exist. There is no need for the
file to contain any actual data. Indeed, actually using the file for data
storage is strongly disrecommended, as this will foreclose most strategies for
reliable update. Use a separate lockfile instead.
Ability to obtain the lock corresponds to write permission on the file (and of
course permission to create the file, if it does not already exist). However,
processes with only read permission on the file can prevent the lock being
acquired at all; therefore lockfiles should not usually be world-readable.
When a (group of) processes wishes to acquire the lock, it should open the file
(with
O_CREAT) and lock it with
fcntl(2) F_RWLCK,
operation
F_SETLK or
F_SETLKW. If this succeeds it should fstat
the file descriptor it has, and the file by its path. If the device and inode
match then the lock has been acquired and remains acquired until that group of
processes changes which file the name refers to, deletes the file, or releases
the fcntl lock. If they do not then another process acquired the lock and
deleted the file in the meantime; you must now close your filedescriptor and
start again.
with-lock-ex follows this specification.
Note that
flock(2) is a different kind of lock to
fcntl(2).
with-lock-ex uses
fcntl.
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.
COPYRIGHT¶
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.
SEE ALSO¶
fcntl(2),
flock(2),
chmod(2)