1.\" $NetBSD: shlock.1,v 1.14 2014/03/18 18:20:45 riastradh Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Erik E. Fair. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd November 2, 2012 31.Dt SHLOCK 1 32.Os 33.Sh NAME 34.Nm shlock 35.Nd create or verify a lock file for shell scripts 36.Sh SYNOPSIS 37.Nm 38.Op Fl du 39.Op Fl p Ar PID 40.Fl f 41.Ar lockfile 42.Sh DESCRIPTION 43The 44.Nm 45command can create or verify a lock file on behalf of a shell or 46other script program. 47When it attempts to create a lock file, if one already exists, 48.Nm 49verifies that it is or is not valid. 50If valid, 51.Nm 52will exit with a non-zero exit code. 53If invalid, 54.Nm 55will remove the lock file, and 56create a new one. 57.Pp 58.Nm 59uses the 60.Xr link 2 61system call to make the final target lock file, which is an atomic 62operation (i.e. "dot locking", so named for this mechanism's original 63use for locking system mailboxes). 64It puts the process ID ("PID") from the command line into the 65requested lock file. 66.Pp 67.Nm 68verifies that an extant lock file is still valid by 69using 70.Xr kill 2 71with a zero signal to check for the existence of the process that 72holds the lock. 73.Pp 74The 75.Fl d 76option causes 77.Nm 78to be verbose about what it is doing. 79.Pp 80The 81.Fl f 82argument with 83.Ar lockfile 84is always required. 85.Pp 86The 87.Fl p 88option with 89.Ar PID 90is given when the program is to create a lock file; when absent, 91.Nm 92will simply check for the validity of the lock file. 93.Pp 94The 95.Fl u 96option causes 97.Nm 98to read and write the PID as a binary pid_t, instead of as ASCII, 99to be compatible with the locks created by UUCP. 100.Sh EXIT STATUS 101A zero exit code indicates a valid lock file. 102.Sh EXAMPLES 103.Ss BOURNE SHELL 104.Bd -literal 105#!/bin/sh 106lckfile=/tmp/foo.lock 107if shlock -f ${lckfile} -p $$ 108then 109# do what required the lock 110 rm ${lckfile} 111else 112 echo Lock ${lckfile} already held by `cat ${lckfile}` 113fi 114.Ed 115.Ss C SHELL 116.Bd -literal 117#!/bin/csh -f 118set lckfile=/tmp/foo.lock 119shlock -f ${lckfile} -p $$ 120if ($status == 0) then 121# do what required the lock 122 rm ${lckfile} 123else 124 echo Lock ${lckfile} already held by `cat ${lckfile}` 125endif 126.Ed 127.Pp 128The examples assume that the file system where the lock file is to 129be created is writable by the user, and has space available. 130.Sh SEE ALSO 131.Xr flock 1 132.Sh HISTORY 133.Nm 134was written for the first Network News Transfer Protocol (NNTP) 135software distribution, released in March 1986. 136The algorithm was suggested by Peter Honeyman, 137from work he did on HoneyDanBer UUCP. 138.Sh AUTHORS 139.An Erik E. Fair Aq Mt fair@clock.org 140.Sh BUGS 141Does not work on NFS or other network file system on different 142systems because the disparate systems have disjoint PID spaces. 143.Pp 144Cannot handle the case where a lock file was not deleted, the 145process that created it has exited, and the system has created a 146new process with the same PID as in the dead lock file. 147The lock file will appear to be valid even though the process is 148unrelated to the one that created the lock in the first place. 149Always remove your lock files after you're done. 150