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