1Please read the README file in this directory first. 2.ex 3.Id $Id: lockfile.man,v 1.18 2001/06/23 08:22:25 guenther Exp $ 4.TH LOCKFILE 1 \*(Dt BuGless 5.na 6.SH NAME 7lockfile \- conditional semaphore-file creator 8.SH SYNOPSIS 9.B lockfile 10.I "\fB\-\fPsleeptime" 11| 12.I "\fB\-r \fPretries" 13| 14.if n .ti +0.5i 15.I "\fB\-l \fPlocktimeout" 16| 17.I "\fB\-s \fPsuspend" 18| 19.B "\-!" 20| 21.B "\-ml" 22| 23.B "\-mu" 24| 25.I filename 26\&.\|.\|. 27.ad 28.SH DESCRIPTION 29.B lockfile 30can be used to create one or more 31.I semaphore 32.IR files . 33If lockfile can't create all the specified files (in the specified order), 34it waits 35.I sleeptime 36(defaults to @DEFlocksleep@) seconds and retries the last file that didn't 37succeed. You can specify the number of 38.I retries 39to do until failure is returned. 40If the number of 41.I retries 42is \-1 (default, i.e., 43.BR \-r\-1 ) 44lockfile will retry forever. 45.PP 46If the number of 47.I retries 48expires before all files have been created, lockfile returns failure and 49removes all the files it created up till that point. 50.PP 51Using lockfile as the condition of a loop in a shell script can be done 52easily by using the 53.B \-! 54flag to invert the exit status. To prevent infinite loops, failures 55for any reason other than the lockfile already existing are not 56inverted to success but rather are still returned as failures. 57.PP 58All flags can be specified anywhere on the command line, they will be 59processed when encountered. The command line is simply parsed from 60left to right. 61.PP 62All files created by lockfile will be read-only, and therefore 63will have to be removed with 64.B rm 65.BR \-f . 66.PP 67If you specify a 68.I locktimeout 69then a lockfile will be removed by force after locktimeout seconds have 70passed since the lockfile was last modified/created (most likely by some 71other program that unexpectedly died a long time ago, and hence could not clean 72up any leftover lockfiles). Lockfile is clock skew immune. After a lockfile 73has been removed by force, a suspension of 74.I suspend 75seconds (defaults to @DEFsuspend@) is taken into account, in order to prevent 76the inadvertent immediate removal of any newly created lockfile by another 77program (compare 78.BR SUSPEND 79in 80.BR procmail (1)). 81.SS "Mailbox locks" 82If the permissions on the system mail spool directory allow it, or if lockfile 83is suitably setgid, it will be able to lock and unlock your system mailbox by 84using the options 85.B "\-ml" 86and 87.B "\-mu" 88respectively. 89.SH EXAMPLES 90Suppose you want to make sure that access to the file "important" is 91serialised, i.e., no more than one program or shell script should be allowed 92to access it. For simplicity's sake, let's suppose that it is a shell 93script. In this case you could solve it like this: 94.RS 95\&.\|.\|. 96lockfile important.lock 97\&.\|.\|. 98access_"important"_to_your_hearts_content 99\&.\|.\|. 100rm \-f important.lock 101\&.\|.\|. 102.RE 103Now if all the scripts that access "important" follow this guideline, you 104will be assured that at most one script will be executing between the 105`lockfile' and the `rm' commands. 106.SH ENVIRONMENT 107.TP 2.3i 108.B LOGNAME 109used as a hint to determine the invoker's loginname 110.SH FILES 111.TP 2.3i 112.B /etc/passwd 113to verify and/or correct the invoker's loginname (and to find out his HOME 114directory, if needed) 115.TP 116.B @MAILSPOOLDIR@$LOGNAME@DEFlockext@ 117lockfile for the system mailbox, the environment variables present in here 118will not be taken from the environment, but will be determined by looking 119in /etc/passwd 120.SH "SEE ALSO" 121.na 122.nh 123.BR rm (1), 124.BR mail (1), 125.BR binmail (1), 126.BR sendmail (8), 127.BR procmail (1) 128.hy 129.ad 130.SH DIAGNOSTICS 131.TP 2.3i 132Filename too long, .\|.\|. 133Use shorter filenames. 134.TP 135Forced unlock denied on "x" 136No write permission in the directory where lockfile "x" resides, or more than 137one lockfile trying to force a lock at exactly the same time. 138.TP 139Forcing lock on "x" 140Lockfile "x" is going to be removed by force because of a timeout 141(compare 142.BR LOCKTIMEOUT 143in 144.BR procmail (1)). 145.TP 146Out of memory, .\|.\|. 147The system is out of swap space. 148.TP 149Signal received, .\|.\|. 150Lockfile will remove anything it created till now and terminate. 151.TP 152Sorry, .\|.\|. 153The 154.I retries 155limit has been reached. 156.TP 157Truncating "x" and retrying lock 158"x" does not seem to be a valid filename. 159.TP 160Try praying, .\|.\|. 161Missing subdirectories or insufficient privileges. 162.SH BUGS 163Definitely less than one. 164.SH WARNINGS 165The behavior of the 166.B \-! 167flag, while useful, is not necessarily intuitive or consistent. When 168testing lockfile's return value, shell script writers should consider 169carefully whether they want to use the 170.B \-! 171flag, simply reverse the test, or do a switch on the exact exitcode. 172In general, the 173.B \-! 174flag should only be used when lockfile is the conditional of a loop. 175.SH MISCELLANEOUS 176Lockfile is NFS-resistant and eight-bit clean. 177.SH NOTES 178Calling up lockfile with the \-@HELPOPT1@ or \-@HELPOPT2@ options will cause 179it to display a command-line help page. Calling it up with the \-@VERSIONOPT@ 180option will cause it to display its version information. 181.PP 182Multiple 183.B \-! 184flags will toggle the return status. 185.PP 186Since flags can occur anywhere on the command line, any filename starting 187with a '-' has to be preceded by './'. 188.PP 189The number of 190.I retries 191will not be reset when any following file is being created (i.e., they are 192simply used up). It can, however, be reset by specifying 193.RI \-r newretries 194after every file on the command line. 195.PP 196Although files with any name can be used as lockfiles, it is common practice 197to use the extension `.lock' to lock mailfolders (it is appended to the 198mailfolder name). In case one does not want to have to worry about too long 199filenames and does not have to conform to any other lockfilename convention, 200then an excellent way to generate a lockfilename corresponding to some already 201existing file is by taking the prefix `lock.' and appending the i-node number 202of the file which is to be locked. 203