Debian Codegraph @

upstream/debian-unstable/man1/lockfile.1

raw
1 .\"if n .pl +(135i-\n(.pu)
2 .de Id
3 .ds Rv \\$3
4 .ds Dt \\$4
5 ..
6 .Id $Id: lockfile.man,v 1.18 2001/06/23 08:22:25 guenther Exp $
7 .TH LOCKFILE 1 \*(Dt BuGless
8 .rn SH Sh
9 .de SH
10 .br
11 .ne 11
12 .Sh "\\$1"
13 ..
14 .rn SS Ss
15 .de SS
16 .br
17 .ne 10
18 .Ss "\\$1"
19 ..
20 .rn TP Tp
21 .de TP
22 .br
23 .ne 9
24 .Tp \\$1
25 ..
26 .rn RS Rs
27 .de RS
28 .na
29 .nf
30 .Rs
31 ..
32 .rn RE Re
33 .de RE
34 .Re
35 .fi
36 .ad
37 ..
38 .de Sx
39 .PP
40 .ne \\$1
41 .RS
42 ..
43 .de Ex
44 .RE
45 .PP
46 ..
47 .na
48 .SH NAME
49 lockfile \- conditional semaphore-file creator
50 .SH SYNOPSIS
51 .B lockfile
52 .I "\fB\-\fPsleeptime"
53 |
54 .I "\fB\-r \fPretries"
55 |
56 .if n .ti +0.5i
57 .I "\fB\-l \fPlocktimeout"
58 |
59 .I "\fB\-s \fPsuspend"
60 |
61 .B "\-!"
62 |
63 .B "\-ml"
64 |
65 .B "\-mu"
66 |
67 .I filename
68 \&.\|.\|.
69 .ad
70 .SH DESCRIPTION
71 .B lockfile
72 can be used to create one or more
73 .I semaphore
74 .IR files .
75 If lockfile can't create all the specified files (in the specified order),
76 it waits
77 .I sleeptime
78 (defaults to 8) seconds and retries the last file that didn't
79 succeed. You can specify the number of
80 .I retries
81 to do until failure is returned.
82 If the number of
83 .I retries
84 is \-1 (default, i.e.,
85 .BR \-r\-1 )
86 lockfile will retry forever.
87 .PP
88 If the number of
89 .I retries
90 expires before all files have been created, lockfile returns failure and
91 removes all the files it created up till that point.
92 .PP
93 Using lockfile as the condition of a loop in a shell script can be done
94 easily by using the
95 .B \-!
96 flag to invert the exit status. To prevent infinite loops, failures
97 for any reason other than the lockfile already existing are not
98 inverted to success but rather are still returned as failures.
99 .PP
100 All flags can be specified anywhere on the command line, they will be
101 processed when encountered. The command line is simply parsed from
102 left to right.
103 .PP
104 All files created by lockfile will be read-only, and therefore
105 will have to be removed with
106 .B rm
107 .BR \-f .
108 .PP
109 If you specify a
110 .I locktimeout
111 then a lockfile will be removed by force after locktimeout seconds have
112 passed since the lockfile was last modified/created (most likely by some
113 other program that unexpectedly died a long time ago, and hence could not clean
114 up any leftover lockfiles). Lockfile is clock skew immune. After a lockfile
115 has been removed by force, a suspension of
116 .I suspend
117 seconds (defaults to 16) is taken into account, in order to prevent
118 the inadvertent immediate removal of any newly created lockfile by another
119 program (compare
120 .BR SUSPEND
121 in
122 .BR procmail (1)).
123 .SS "Mailbox locks"
124 If the permissions on the system mail spool directory allow it, or if lockfile
125 is suitably setgid, it will be able to lock and unlock your system mailbox by
126 using the options
127 .B "\-ml"
128 and
129 .B "\-mu"
130 respectively.
131 .SH EXAMPLES
132 Suppose you want to make sure that access to the file "important" is
133 serialised, i.e., no more than one program or shell script should be allowed
134 to access it. For simplicity's sake, let's suppose that it is a shell
135 script. In this case you could solve it like this:
136 .RS
137 \&.\|.\|.
138 lockfile important.lock
139 \&.\|.\|.
140 access_"important"_to_your_hearts_content
141 \&.\|.\|.
142 rm \-f important.lock
143 \&.\|.\|.
144 .RE
145 Now if all the scripts that access "important" follow this guideline, you
146 will be assured that at most one script will be executing between the
147 `lockfile' and the `rm' commands.
148 .SH ENVIRONMENT
149 .TP 2.3i
150 .B LOGNAME
151 used as a hint to determine the invoker's loginname
152 .SH FILES
153 .TP 2.3i
154 .B /etc/passwd
155 to verify and/or correct the invoker's loginname (and to find out his HOME
156 directory, if needed)
157 .TP
158 .B /var/mail/$LOGNAME.lock
159 lockfile for the system mailbox, the environment variables present in here
160 will not be taken from the environment, but will be determined by looking
161 in /etc/passwd
162 .SH "SEE ALSO"
163 .na
164 .nh
165 .BR rm (1),
166 .BR mail (1),
167 .BR sendmail (8),
168 .BR procmail (1)
169 .hy
170 .ad
171 .SH DIAGNOSTICS
172 .TP 2.3i
173 Filename too long, .\|.\|.
174 Use shorter filenames.
175 .TP
176 Forced unlock denied on "x"
177 No write permission in the directory where lockfile "x" resides, or more than
178 one lockfile trying to force a lock at exactly the same time.
179 .TP
180 Forcing lock on "x"
181 Lockfile "x" is going to be removed by force because of a timeout
182 (compare
183 .BR LOCKTIMEOUT
184 in
185 .BR procmail (1)).
186 .TP
187 Out of memory, .\|.\|.
188 The system is out of swap space.
189 .TP
190 Signal received, .\|.\|.
191 Lockfile will remove anything it created till now and terminate.
192 .TP
193 Sorry, .\|.\|.
194 The
195 .I retries
196 limit has been reached.
197 .TP
198 Truncating "x" and retrying lock
199 "x" does not seem to be a valid filename.
200 .TP
201 Try praying, .\|.\|.
202 Missing subdirectories or insufficient privileges.
203 .SH BUGS
204 Definitely less than one.
205 .SH WARNINGS
206 The behavior of the
207 .B \-!
208 flag, while useful, is not necessarily intuitive or consistent. When
209 testing lockfile's return value, shell script writers should consider
210 carefully whether they want to use the
211 .B \-!
212 flag, simply reverse the test, or do a switch on the exact exitcode.
213 In general, the
214 .B \-!
215 flag should only be used when lockfile is the conditional of a loop.
216 .SH MISCELLANEOUS
217 Lockfile is NFS-resistant and eight-bit clean.
218 .SH NOTES
219 Calling up lockfile with the \-h or \-? options will cause
220 it to display a command-line help page. Calling it up with the \-v
221 option will cause it to display its version information.
222 .PP
223 Multiple
224 .B \-!
225 flags will toggle the return status.
226 .PP
227 Since flags can occur anywhere on the command line, any filename starting
228 with a '-' has to be preceded by './'.
229 .PP
230 The number of
231 .I retries
232 will not be reset when any following file is being created (i.e., they are
233 simply used up). It can, however, be reset by specifying
234 .RI \-r newretries
235 after every file on the command line.
236 .PP
237 Although files with any name can be used as lockfiles, it is common practice
238 to use the extension `.lock' to lock mailfolders (it is appended to the
239 mailfolder name). In case one does not want to have to worry about too long
240 filenames and does not have to conform to any other lockfilename convention,
241 then an excellent way to generate a lockfilename corresponding to some already
242 existing file is by taking the prefix `lock.' and appending the i-node number
243 of the file which is to be locked.
244 .Sh SOURCE
245 This program is part of the
246 .I procmail mail-processing-package
247 (v3.23pre) available at http://www.procmail.org/ or
248 ftp.procmail.org in
249 .BR pub/procmail/ .
250 .Sh MAILINGLIST
251 There exists a mailinglist for questions relating to any program in the
252 procmail package:
253 .RS
254 <[email protected]>
255 .RS
256 for submitting questions/answers.
257 .RE
258 <[email protected]>
259 .RS
260 for subscription requests.
261 .RE
262 .PP
263 .RE
264 If you would like to stay informed about new versions and official patches send
265 a subscription request to
266 .RS
267 [email protected]
268 .RE
269 (this is a readonly list).
270 .SH AUTHORS
271 Stephen R. van den Berg
272 .RS
273 <[email protected]>
274 .RE
275 Philip A. Guenther
276 .RS
277 <[email protected]>
278 .RE
279 .\".if n .pl -(\n(.tu-1i)
280 .rm SH
281 .rn Sh SH
282 .rm SS
283 .rn Ss SS
284 .rm TP
285 .rn Tp TP
286 .rm RS
287 .rn Rs RS
288 .rm RE
289 .rn Re RE