1.\" $NetBSD: shlock.1,v 1.8 2004/07/13 12:14:07 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.Op Fl du 12.Op Fl p Ar PID 13.Fl f 14.Ar lockfile 15.Sh DESCRIPTION 16The 17.Nm 18command can create or verify a lock file on behalf of a shell or 19other script program. 20When it attempts to create a lock file, if one already exists, 21.Nm 22verifies that it is or is not valid. 23If valid, 24.Nm 25will exit with a non-zero exit code. 26If invalid, 27.Nm 28will remove the lock file, and 29create a new one. 30.Pp 31.Nm 32uses the 33.Xr rename 2 34system call to make the final target lock file, which is an atomic 35operation (i.e. "dot locking", so named for this mechanism's original 36use for locking system mailboxes). 37It puts the process ID ("PID") from the command line into the 38requested lock file. 39.Pp 40.Nm 41verifies that an extant lock file is still valid by 42using 43.Xr kill 2 44with a zero signal to check for the existence of the process that 45holds the lock. 46.Pp 47The 48.Fl d 49option causes 50.Nm 51to be verbose about what it is doing. 52.Pp 53The 54.Fl f 55argument with 56.Ar lockfile 57is always required. 58.Pp 59The 60.Fl p 61option with 62.Ar PID 63is given when the program is to create a lock file; when absent, 64.Nm 65will simply check for the validity of the lock file. 66.Pp 67The 68.Fl u 69option causes 70.Nm 71to read and write the PID as a binary pid_t, instead of as ASCII, 72to be compatible with the locks created by UUCP. 73.Sh EXIT STATUS 74A zero exit code indicates a valid lock file. 75.Sh EXAMPLES 76.Ss BOURNE SHELL 77.Bd -literal 78#!/bin/sh 79lckfile=/tmp/foo.lock 80if shlock -f ${lckfile} -p $$ 81then 82# do what required the lock 83 rm ${lckfile} 84else 85 echo Lock ${lckfile} already held by `cat ${lckfile}` 86fi 87.Ed 88.Ss C SHELL 89.Bd -literal 90#!/bin/csh -f 91set lckfile=/tmp/foo.lock 92shlock -f ${lckfile} -p $$ 93if ($status == 0) then 94# do what required the lock 95 rm ${lckfile} 96else 97 echo Lock ${lckfile} already held by `cat ${lckfile}` 98endif 99.Ed 100.Pp 101The examples assume that the file system where the lock file is to 102be created is writable by the user, and has space available. 103.Sh HISTORY 104.Nm 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 AUTHORS 110.An Erik E. Fair Aq fair@clock.org 111.Sh BUGS 112Does not work on NFS or other network file system 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