shlock.1 revision 1.1
1.Dd June 29, 1997 2.Dt SHLOCK 1 3.Os 4.Sh NAME 5.Nm shlock 6.Nd create or verify a lock file for shell scripts 7.Sh SYNOPSIS 8.Nm shlock 9.Fl f 10.Ar lockfile 11.Op Fl p Ar PID 12.Op Fl u 13.Op Fl v 14.Sh DESCRIPTION 15The 16.Nm shlock 17command can create or verify a lock file on behalf of a shell or 18other script program. 19When it attempts to create a lock file, if one already exists, 20.Nm shlock 21verifies that it is or is not valid. 22If valid, 23.Nm shlock 24will exit with a non-zero exit code. 25If invalid, 26.Nm shlock 27will remove the lock file, and 28create a new one. 29.Pp 30.Nm shlock 31uses the 32.Xr rename 2 33system call to make the final target lock file, which is an atomic 34operation (i.e. "dot locking", so named for this mechanism's original 35use for locking system mailboxes). 36It puts the process ID ("PID") from the command line into the 37requested lock file. 38.Pp 39.Nm shlock 40verifies that an extant lock file is still valid by 41using 42.Xr kill 2 43with a zero signal to check for the existence of the process that 44holds the lock. 45.Pp 46The 47.Fl f 48argument with 49.Ar lockfile 50is always required. 51.Pp 52The 53.Fl p 54option with 55.Ar PID 56is given when the program is to create a lock file; when absent, 57.Nm shlock 58will simply check for the validity of the lock file. 59.Pp 60The 61.Fl u 62option causes 63.Nm shlock 64to read and write the PID as a binary pid_t, instead of as ASCII, 65to be compatible with the locks created by UUCP. 66.Pp 67The 68.Fl v 69option causes 70.Nm shlock 71to be verbose about what it is doing. 72.Sh RETURN VALUES 73A zero exit code indicates a valid lock file. 74.Sh EXAMPLES 75.Ss BOURNE SHELL 76.Bd -literal 77#!/bin/sh 78lckfile=/tmp/foo.lock 79if shlock -f ${lckfile} -p $$ 80then 81# do what required the lock 82 rm ${lckfile} 83else 84 echo Lock ${lckfile} already held by `cat ${lckfile}` 85fi 86.Ed 87.Ss C SHELL 88.Bd -literal 89#!/bin/csh -f 90set lckfile=/tmp/foo.lock 91shlock -f ${lckfile} -p $$ 92if ($status == 0) then 93# do what required the lock 94 rm ${lckfile} 95else 96 echo Lock ${lckfile} already held by `cat ${lckfile}` 97endif 98.Ed 99 100.Pp 101The examples assume that the filesystem where the lock file is to 102be created is writeable by the user, and has space available. 103.Sh HISTORY 104.Nm shlock 105was written for the first Network News Transfer Protocol (NNTP) 106software distribution, released in March 1986. 107The algorithm was suggested by Peter Honeyman, 108from work he did on HoneyDanBer UUCP. 109.Sh AUTHOR 110Erik E. Fair <fair@clock.org> 111.Sh BUGS 112Does not work on NFS or other network filesystem on different 113systems because the disparate systems have disjoint PID spaces. 114.Pp 115Cannot handle the case where a lock file was not deleted, the 116process that created it has exited, and the system has created a 117new process with the same PID as in the dead lock file. 118The lock file will appear to be valid even though the process is 119unrelated to the one that created the lock in the first place. 120Always remove your lock files after you're done. 121