1 .TH WITH-LOCK-EX "1" "July 2003" "Debian" "Chiark-utils-bin"
3 with-lock-ex \- file locker
6 .RB [\| \-w \||\| \-q \||\| \-f \|]
11 with-lock-ex will open and lock the lockfile for writing and then feed
12 the remainder of its arguments to
14 when that process terminates the fd will be closed and the file
15 unlocked automatically by the kernel.
17 If the file does not exist it is created, with permissions
19 for each user class for which the umask has
27 fail if the lock cannot be acquired
30 silently do nothing (ie, exit 0 instead of executing the specified
31 process) if the lock cannot be acquired
33 The locking protocol used does not suffer from stale locks. If the
34 lock cannot be acquired, one or more running processes must currently
35 hold the lock; if the lock needs to be freed those processes should be
38 Under no circumstances should `stale lock cleaner' cron jobs, or the
39 like, be instituted. In systems where a great many locks may exist,
40 old lockfiles may be removed from cron but only if each lock is
41 acquired before the lockfile is removed, for example with
48 There is no deadlock detection. In a system with several locks, a
49 lock hierarchy should be established, such that for every pair of
54 which a process might lock simultaneously, either
58 where the relation > is transitive and noncyclic.
60 Then, for any two locks
66 it is forbidden to acquire
80 (There are more complicated ways of avoiding deadlocks, but a lock
81 hierarchy is simple to understand and implement. If it does not meet
82 your needs, consult the literature.)
84 The locking protocol used by
88 The lock is held by a process (or group of processes) which holds an
89 fcntl exclusive lock on the first byte of the plain file which has the
90 specified name. A holder of the lock (and only a holder of the lock)
91 may delete the file or change the inode to which the name refers, and
92 as soon as it does so it ceases to hold the lock.
94 Any process may create the file if it does not exist. There is no
95 need for the file to contain any actual data. Indeed, actually using
96 the file for data storage is strongly disrecommended, as this will
97 foreclose most strategies for reliable update. Use a separate
100 Ability to obtain the lock corresponds to write permission on the file
101 (and of course permission to create the file, if it does not already
102 exist). However, processes with only read permission on the file can
103 prevent the lock being acquired at all; therefore lockfiles should not
104 usually be world-readable.
106 When a (group of) processes wishes to acquire the lock, it should open
117 If this succeeds it should fstat the file descriptor it has, and the
118 file by its path. If the device and inode match then the lock has
119 been acquired and remains acquired until that group of processes
120 changes which file the name refers to, deletes the file, or releases
121 the fcntl lock. If they do not then another process acquired the lock
122 and deleted the file in the meantime; you must now close your
123 filedescriptor and start again.
125 follows this specification.
129 is a different kind of lock to
135 This Manual page was written by Matthew Vernon <matthew@debian.org>
136 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
137 may be used by anyone.
139 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
140 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public