Penguin
Recent Changes
Annotated edit history of lockfile(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 LOCKFILE
2 !!!LOCKFILE
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 ENVIRONMENT
8 FILES
9 SEE ALSO
10 DIAGNOSTICS
11 BUGS
12 WARNINGS
13 MISCELLANEOUS
14 NOTES
15 SOURCE
16 MAILINGLIST
17 AUTHORS
18 ----
19 !!NAME
20
21
22 lockfile - conditional semaphore-file creator
23 !!SYNOPSIS
24
25
26 __lockfile -__''sleeptime'' | __-r__ ''retries''
27 | __-l__ ''locktimeout'' | __-s__ ''suspend'' |
28 __-!__ | __-ml__ | __-mu__ | ''filename''
29 ...
30 !!DESCRIPTION
31
32
33 __lockfile__ can be used to create one or more
34 ''semaphore files''. If lockfile can't create all the
35 specified files (in the specified order), it waits
36 ''sleeptime'' (defaults to 8) seconds and retries the
37 last file that didn't succeed. You can specify the number of
38 ''retries'' to do until failure is returned. If the
39 number of ''retries'' is -1 (default, i.e., __-r-1__)
40 lockfile will retry forever.
41
42
43 If the number of ''retries'' expires before all files
44 have been created, lockfile returns failure and removes all
45 the files it created up till that point.
46
47
48 Using lockfile as the condition of a loop in a shell script
49 can be done easily by using the __-!__ flag to invert the
50 exit status. To prevent infinite loops, failures for any
51 reason other than the lockfile already existing are not
52 inverted to success but rather are still returned as
53 failures.
54
55
56 All flags can be specified anywhere on the command line,
57 they will be processed when encountered. The command line is
58 simply parsed from left to right.
59
60
61 All files created by lockfile will be read-only, and
62 therefore will have to be removed with __rm
63 -f__.
64
65
66 If you specify a ''locktimeout'' then a lockfile will be
67 removed by force after locktimeout seconds have passed since
68 the lockfile was last modified/created (most likely by some
69 other program that unexpectedly died a long time ago, and
70 hence could not clean up any leftover lockfiles). Lockfile
71 is clock skew immune. After a lockfile has been removed by
72 force, a suspension of ''suspend'' seconds (defaults to
73 16) is taken into account, in order to prevent the
74 inadvertent immediate removal of any newly created lockfile
75 by another program (compare __SUSPEND__ in
76 procmail(1)).
77
78
79 __Mailbox locks__
80
81
82 If the permissions on the system mail spool directory allow
83 it, or if lockfile is suitably setgid, it will be able to
84 lock and unlock your system mailbox by using the options
85 __-ml__ and __-mu__ respectively.
86 !!EXAMPLES
87
88
89 Suppose you want to make sure that access to the file
90
91
92 ...
93 lockfile important.lock
94 ...
95 access_
96 Now if all the scripts that access
97 !!ENVIRONMENT
98
99
100 __LOGNAME__ used as a hint to determine the invoker's
101 loginname
102 !!FILES
103
104
105 __/etc/passwd__ to verify and/or correct the invoker's
106 loginname (and to find out his HOME directory, if
107 needed)
108
109
110 __/var/mail/$LOGNAME.lock__
111
112
113 lockfile for the system mailbox, the environment variables
114 present in here will not be taken from the environment, but
115 will be determined by looking in /etc/passwd
116 !!SEE ALSO
117
118
119 rm(1), mail(1), binmail(1),
120 sendmail(8), procmail(1)
121 !!DIAGNOSTICS
122
123
124 Filename too long, ...
125
126
127 Use shorter filenames.
128
129
130 Forced unlock denied on
131
132
133 No write permission in the directo- ry where lockfile
134
135
136 Forcing lock on
137
138
139 Lockfile
140 LOCKTIMEOUT__ in
141 procmail(1)).
142
143
144 Out of memory, ...
145
146
147 The system is out of swap space.
148
149
150 Signal received, ...
151
152
153 Lockfile will remove anything it created till now and
154 terminate.
155
156
157 Sorry, ... The ''retries'' limit has been
158 reached.
159
160
161 Truncating
162
163
164
165
166 Try praying, ...
167
168
169 Missing subdirectories or insuffi- cient
170 privileges.
171 !!BUGS
172
173
174 Definitely less than one.
175 !!WARNINGS
176
177
178 The behavior of the __-!__ flag, while useful, is not
179 neces- sarily intuitive or consistent. When testing
180 lockfile's return value, shell script writers should
181 consider care- fully whether they want to use the __-!__
182 flag, simply re- verse the test, or do a switch on the exact
183 exitcode. In general, the __-!__ flag should only be used
184 when lockfile is the conditional of a loop.
185 !!MISCELLANEOUS
186
187
188 Lockfile is NFS-resistant and eight-bit clean.
189 !!NOTES
190
191
192 Calling up lockfile with the -h or -? options will cause it
193 to display a command-line help page. Calling it up with the
194 -v option will cause it to display its version
195 information.
196
197
198 Multiple __-!__ flags will toggle the return
199 status.
200
201
202 Since flags can occur anywhere on the command line, any
203 filename starting with a '-' has to be preceded by
204 './'.
205
206
207 The number of ''retries'' will not be reset when any
208 following file is being created (i.e., they are simply used
209 up). It can, however, be reset by specifying
210 -r''newretries'' after every file on the command
211 line.
212
213
214 Although files with any name can be used as lockfiles, it is
215 common practice to use the extension `.lock' to lock
216 mailfolders (it is appended to the mailfolder name). In case
217 one does not want to have to worry about too long filenames
218 and does not have to conform to any other lock- filename
219 convention, then an excellent way to generate a lockfilename
220 corresponding to some already existing file is by taking the
221 prefix `lock.' and appending the i-node number of the file
222 which is to be locked.
223 !!SOURCE
224
225
226 This program is part of the ''procmail
227 mail-processing-pack- age'' (v3.22) available at
228 http://www.procmail.org/ or ftp.procmail.org in
229 __pub/procmail/__.
230 !!MAILINGLIST
231
232
233 There exists a mailinglist for questions relating to any
234 program in the procmail package:
235
236
237
238
239
240 for subscription requests.
241
242
243 If you would like to stay informed about new versions and
244 official patches send a subscription request to
245
246
247 procmail-announce-request@procmail.org
248 (this is a readonly list).
249 !!AUTHORS
250
251
252 Stephen R. van den Berg
253
254
255
256 Philip A. Guenther
257
258
259
260 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.