chiark / gitweb /
fishdescriptor: fix error handling
[chiark-utils.git] / cprogs / with-lock-ex.1
1 .TH WITH-LOCK-EX "1" "July 2003" "Debian" "Chiark-utils-bin"
2 .SH NAME
3 with-lock-ex \- file locker
4 .SH SYNOPSIS
5 .B with-lock-ex
6 .BR \-w \||\| \-q \||\| \-f
7 .I lockfile command 
8 .IR args \ \|.\|.\|.
9 .br
10 .SH DESCRIPTION
11 with-lock-ex will open and lock the lockfile for writing and then feed
12 the remainder of its arguments to
13 .BR exec (2);
14 when that process terminates the fd will be closed and the file
15 unlocked automatically by the kernel.
16 .PP
17 If the file does not exist it is created, with permissions
18 .B rw
19 for each user class for which the umask has
20 .BR w .
21 .SH OPTIONS
22 .TP
23 .B \-w
24 Wait for the lock to be available.
25 .TP
26 .B \-f
27 Fail (printing a message to stderr and exiting 255) if the lock cannot
28 be acquired immediately because another process has it.
29 .TP
30 .B \-q
31 Silently do nothing (ie, exit 0 instead of executing the specified
32 process) if the lock cannot be acquired immediately because another
33 process has it.
34 .SH STALE LOCKS
35 The locking protocol used does not suffer from stale locks.  If the
36 lock cannot be acquired, one or more running processes must currently
37 hold the lock; if the lock needs to be freed those processes should be
38 killed.
39 .PP
40 Under no circumstances should `stale lock cleaner' cron jobs, or the
41 like, be instituted.  In systems where a great many locks may exist,
42 old lockfiles may be removed from cron but only if each lock is
43 acquired before the lockfile is removed, for example with
44 .IP
45 .B with-lock-ex -q
46 .I lockfile
47 .B rm
48 .I lockfile
49 .SH DEADLOCKS
50 There is no deadlock detection.  In a system with several locks, a
51 lock hierarchy should be established, such that for every pair of
52 locks
53 .I A
54 and
55 .I B
56 which a process might lock simultaneously, either
57 .IR A > B
58 or
59 .IR B > A
60 where the relation > is transitive and noncyclic.
61 .PP
62 Then, for any two locks
63 .I X
64 and
65 .I Y
66 with
67 .IR X > Y
68 it is forbidden to acquire
69 .I X
70 while holding
71 .IR Y .
72 Instead, acquire
73 .I X
74 first, or release
75 .I Y
76 before (re)acquiring
77 .I X
78 and
79 .I Y
80 in that order.
81 .PP
82 (There are more complicated ways of avoiding deadlocks, but a lock
83 hierarchy is simple to understand and implement.  If it does not meet
84 your needs, consult the literature.)
85 .SH LOCKING PROTOCOL
86 The locking protocol used by
87 .B with-lock-ex
88 is as follows:
89 .PP
90 The lock is held by a process (or group of processes) which holds an
91 fcntl exclusive lock on the first byte of the plain file which has the
92 specified name.  A holder of the lock (and only a holder of the lock)
93 may delete the file or change the inode to which the name refers, and
94 as soon as it does so it ceases to hold the lock.
95 .PP
96 Any process may create the file if it does not exist.  There is no
97 need for the file to contain any actual data.  Indeed, actually using
98 the file for data storage is strongly disrecommended, as this will
99 foreclose most strategies for reliable update.  Use a separate
100 lockfile instead.
101 .PP
102 Ability to obtain the lock corresponds to write permission on the file
103 (and of course permission to create the  file, if it does not already
104 exist).  However, processes with only read permission on the file can
105 prevent the lock being acquired at all; therefore lockfiles should not
106 usually be world-readable.
107 .PP
108 When a (group of) processes wishes to acquire the lock, it should open
109 the file
110 (with
111 .BR O_CREAT )
112 and lock it with
113 .BR fcntl (2)
114 .BR F_RWLCK ,
115 operation
116 .B F_SETLK
117 or
118 .BR F_SETLKW .
119 If this succeeds it should fstat the file descriptor it has, and the
120 file by its path.  If the device and inode match then the lock has
121 been acquired and remains acquired until that group of processes
122 changes which file the name refers to, deletes the file, or releases
123 the fcntl lock.  If they do not then another process acquired the lock
124 and deleted the file in the meantime; you must now close your
125 filedescriptor and start again.
126 .B with-lock-ex
127 follows this specification.
128 .PP
129 Note that
130 .BR flock (2)
131 is a different kind of lock to
132 .BR fcntl (2).
133 .B with-lock-ex
134 uses
135 .BR fcntl .
136 .SH AUTHOR
137 This Manual page was written by Matthew Vernon <matthew@debian.org>
138 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
139 may be used by anyone.
140 .SH COPYRIGHT
141 with-lock-ex was written by Ian Jackson <ian@chiark.greenend.org.uk>
142 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
143 domain. 
144 .SH "SEE ALSO"
145 .BR fcntl (2),
146 .BR flock (2),
147 .BR chmod (2)