1LOCKFILE(1)                 General Commands Manual                LOCKFILE(1)
2
3
4

NAME

6       lockfile - conditional semaphore-file creator
7

SYNOPSIS

9       lockfile -sleeptime | -r retries |
10            -l locktimeout | -s suspend | -!  | -ml | -mu | filename ...
11

DESCRIPTION

13       lockfile  can  be used to create one or more semaphore files.  If lock‐
14       file can't create all the specified files (in the specified order),  it
15       waits  sleeptime (defaults to 8) seconds and retries the last file that
16       didn't succeed.  You can specify the number  of  retries  to  do  until
17       failure  is  returned.   If the number of retries is -1 (default, i.e.,
18       -r-1) lockfile will retry forever.
19
20       If the number of retries expires before all files  have  been  created,
21       lockfile  returns  failure and removes all the files it created up till
22       that point.
23
24       Using lockfile as the condition of a loop in a shell script can be done
25       easily  by  using  the  -!  flag to invert the exit status.  To prevent
26       infinite loops, failures for any reason other than the lockfile already
27       existing  are  not inverted to success but rather are still returned as
28       failures.
29
30       All flags can be specified anywhere on the command line, they  will  be
31       processed  when  encountered.   The  command line is simply parsed from
32       left to right.
33
34       All files created by lockfile will be  read-only,  and  therefore  will
35       have to be removed with rm -f.
36
37       If  you  specify a locktimeout then a lockfile will be removed by force
38       after locktimeout seconds have passed since the lockfile was last modi‐
39       fied/created  (most likely by some other program that unexpectedly died
40       a long time ago, and hence could not clean up any leftover  lockfiles).
41       Lockfile  is  clock  skew immune.  After a lockfile has been removed by
42       force, a suspension of suspend seconds (defaults to 16) is  taken  into
43       account,  in  order to prevent the inadvertent immediate removal of any
44       newly created lockfile by another program  (compare  SUSPEND  in  proc‐
45       mail(1)).
46
47   Mailbox locks
48       If  the  permissions on the system mail spool directory allow it, or if
49       lockfile is suitably setgid, it will be able to lock  and  unlock  your
50       system mailbox by using the options -ml and -mu respectively.
51

EXAMPLES

53       Suppose  you  want  to make sure that access to the file "important" is
54       serialised, i.e., no more than one program or shell  script  should  be
55       allowed  to access it.  For simplicity's sake, let's suppose that it is
56       a shell script.  In this case you could solve it like this:
57              ...
58              lockfile important.lock
59              ...
60              access_"important"_to_your_hearts_content
61              ...
62              rm -f important.lock
63              ...
64       Now if all the scripts that access "important" follow  this  guideline,
65       you  will  be assured that at most one script will be executing between
66       the `lockfile' and the `rm' commands.
67

ENVIRONMENT

69       LOGNAME                used as a hint to determine the invoker's login‐
70                              name
71

FILES

73       /etc/passwd            to verify and/or correct the invoker's loginname
74                              (and to find out his HOME directory, if needed)
75
76       /var/spool/mail/$LOGNAME.lock
77                              lockfile for the system mailbox, the environment
78                              variables present in here will not be taken from
79                              the environment, but will be determined by look‐
80                              ing in /etc/passwd
81

SEE ALSO

83       rm(1), mail(1), binmail(1), sendmail(8), procmail(1)
84

DIAGNOSTICS

86       Filename too long, ... Use shorter filenames.
87
88       Forced unlock denied on "x"
89                              No write permission in the directory where lock‐
90                              file "x" resides, or more than one lockfile try‐
91                              ing to force a lock at exactly the same time.
92
93       Forcing lock on "x"    Lockfile "x" is going to be removed by force be‐
94                              cause of a timeout (compare LOCKTIMEOUT in proc‐
95                              mail(1)).
96
97       Out of memory, ...     The system is out of swap space.
98
99       Signal received, ...   Lockfile  will  remove  anything it created till
100                              now and terminate.
101
102       Sorry, ...             The retries limit has been reached.
103
104       Truncating "x" and retrying lock
105                              "x" does not seem to be a valid filename.
106
107       Try praying, ...       Missing subdirectories  or  insufficient  privi‐
108                              leges.
109

BUGS

111       Definitely less than one.
112

WARNINGS

114       The  behavior  of  the -!  flag, while useful, is not necessarily intu‐
115       itive or consistent.   When  testing  lockfile's  return  value,  shell
116       script  writers  should consider carefully whether they want to use the
117       -!  flag, simply reverse the test, or do a switch on  the  exact  exit‐
118       code.   In  general,  the -!  flag should only be used when lockfile is
119       the conditional of a loop.
120

MISCELLANEOUS

122       Lockfile is NFS-resistant and eight-bit clean.
123

NOTES

125       Calling up lockfile with the -h or -? options will cause it to  display
126       a  command-line help page.  Calling it up with the -v option will cause
127       it to display its version information.
128
129       Multiple -!  flags will toggle the return status.
130
131       Since flags can occur anywhere on the command line, any filename start‐
132       ing with a '-' has to be preceded by './'.
133
134       The  number of retries will not be reset when any following file is be‐
135       ing created (i.e., they are simply used up).  It can, however, be reset
136       by specifying -rnewretries after every file on the command line.
137
138       Although  files  with  any  name can be used as lockfiles, it is common
139       practice to use the extension `.lock' to lock mailfolders  (it  is  ap‐
140       pended  to  the mailfolder name).  In case one does not want to have to
141       worry about too long filenames and does not have to conform to any oth‐
142       er  lockfilename  convention, then an excellent way to generate a lock‐
143       filename corresponding to some already existing file is by  taking  the
144       prefix  `lock.' and appending the i-node number of the file which is to
145       be locked.
146

SOURCE

148       This program is part of the  procmail  mail-processing-package  (v3.22)
149       available  at http://www.procmail.org/ or ftp.procmail.org in pub/proc‐
150       mail/.
151

MAILINGLIST

153       There exists a mailinglist for questions relating to any program in the
154       procmail package:
155              <procmail-users@procmail.org>
156                     for submitting questions/answers.
157              <procmail-users-request@procmail.org>
158                     for subscription requests.
159
160       If  you  would  like  to  stay informed about new versions and official
161       patches send a subscription request to
162              procmail-announce-request@procmail.org
163       (this is a readonly list).
164

AUTHORS

166       Stephen R. van den Berg
167              <srb@cuci.nl>
168       Philip A. Guenther
169              <guenther@sendmail.com>
170
171
172
173BuGless                           2001/06/23                       LOCKFILE(1)
Impressum