1 .\"if n .pl +(135i-\n(.pu)
6 .Id $Id: lockfile.1,v 1.1 2003/06/16 17:06:40 motoki Exp $
7 .TH LOCKFILE 1 \*(Dt BuGless
49 lockfile \- conditional semaphore-file creator
52 .I "\fB\-\fPsleeptime"
54 .I "\fB\-r \fPretries"
57 .I "\fB\-l \fPlocktimeout"
59 .I "\fB\-s \fPsuspend"
72 can be used to create one or more
75 If lockfile can't create all the specified files (in the specified order),
78 (defaults to 8) seconds and retries the last file that didn't
79 succeed. You can specify the number of
81 to do until failure is returned.
84 is \-1 (default, i.e.,
86 lockfile will retry forever.
90 expires before all files have been created, lockfile returns failure and
91 removes all the files it created up till that point.
93 Using lockfile as the condition of a loop in a shell script can be done
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.
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
104 All files created by lockfile will be read-only, and therefore
105 will have to be removed with
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
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
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
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:
138 lockfile important.lock
140 access_"important"_to_your_hearts_content
142 rm \-f important.lock
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.
151 used as a hint to determine the invoker's loginname
155 to verify and/or correct the invoker's loginname (and to find out his HOME
156 directory, if needed)
158 .B /var/spool/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
174 Filename too long, .\|.\|.
175 Use shorter filenames.
177 Forced unlock denied on "x"
178 No write permission in the directory where lockfile "x" resides, or more than
179 one lockfile trying to force a lock at exactly the same time.
182 Lockfile "x" is going to be removed by force because of a timeout
188 Out of memory, .\|.\|.
189 The system is out of swap space.
191 Signal received, .\|.\|.
192 Lockfile will remove anything it created till now and terminate.
197 limit has been reached.
199 Truncating "x" and retrying lock
200 "x" does not seem to be a valid filename.
203 Missing subdirectories or insufficient privileges.
205 Definitely less than one.
209 flag, while useful, is not necessarily intuitive or consistent. When
210 testing lockfile's return value, shell script writers should consider
211 carefully whether they want to use the
213 flag, simply reverse the test, or do a switch on the exact exitcode.
216 flag should only be used when lockfile is the conditional of a loop.
218 Lockfile is NFS-resistant and eight-bit clean.
220 Calling up lockfile with the \-h or \-? options will cause
221 it to display a command-line help page. Calling it up with the \-v
222 option will cause it to display its version information.
226 flags will toggle the return status.
228 Since flags can occur anywhere on the command line, any filename starting
229 with a '-' has to be preceded by './'.
233 will not be reset when any following file is being created (i.e., they are
234 simply used up). It can, however, be reset by specifying
236 after every file on the command line.
238 Although files with any name can be used as lockfiles, it is common practice
239 to use the extension `.lock' to lock mailfolders (it is appended to the
240 mailfolder name). In case one does not want to have to worry about too long
241 filenames and does not have to conform to any other lockfilename convention,
242 then an excellent way to generate a lockfilename corresponding to some already
243 existing file is by taking the prefix `lock.' and appending the i-node number
244 of the file which is to be locked.
246 This program is part of the
247 .I procmail mail-processing-package
248 (v3.22) available at http://www.procmail.org/ or
252 There exists a mailinglist for questions relating to any program in the
255 <procmail-users@procmail.org>
257 for submitting questions/answers.
259 <procmail-users-request@procmail.org>
261 for subscription requests.
265 If you would like to stay informed about new versions and official patches send
266 a subscription request to
268 procmail-announce-request@procmail.org
270 (this is a readonly list).
272 Stephen R. van den Berg
278 <guenther@sendmail.com>
280 .\".if n .pl -(\n(.tu-1i)