Copyright (c) 2006 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Erik E. Fair.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd November 2, 2012 .Dt SHLOCK 1 .Os .Sh NAME .Nm shlock .Nd create or verify a lock file for shell scripts .Sh SYNOPSIS .Nm .Op Fl du .Op Fl p Ar PID .Fl f .Ar lockfile .Sh DESCRIPTION The .Nm command can create or verify a lock file on behalf of a shell or other script program. When it attempts to create a lock file, if one already exists, .Nm verifies that it is or is not valid. If valid, .Nm will exit with a non-zero exit code. If invalid, .Nm will remove the lock file, and create a new one.
p .Nm uses the .Xr link 2 system call to make the final target lock file, which is an atomic operation (i.e. "dot locking", so named for this mechanism's original use for locking system mailboxes). It puts the process ID ("PID") from the command line into the requested lock file.
p .Nm verifies that an extant lock file is still valid by using .Xr kill 2 with a zero signal to check for the existence of the process that holds the lock.
p The .Fl d option causes .Nm to be verbose about what it is doing.
p The .Fl f argument with .Ar lockfile is always required.
p The .Fl p option with .Ar PID is given when the program is to create a lock file; when absent, .Nm will simply check for the validity of the lock file.
p The .Fl u option causes .Nm to read and write the PID as a binary pid_t, instead of as ASCII, to be compatible with the locks created by UUCP. .Sh EXIT STATUS A zero exit code indicates a valid lock file. .Sh EXAMPLES .Ss BOURNE SHELL d -literal #!/bin/sh lckfile=/tmp/foo.lock if shlock -f ${lckfile} -p $$ then # do what required the lock rm ${lckfile} else echo Lock ${lckfile} already held by `cat ${lckfile}` fi .Ed .Ss C SHELL d -literal #!/bin/csh -f set lckfile=/tmp/foo.lock shlock -f ${lckfile} -p $$ if ($status == 0) then # do what required the lock rm ${lckfile} else echo Lock ${lckfile} already held by `cat ${lckfile}` endif .Ed
p The examples assume that the file system where the lock file is to be created is writable by the user, and has space available. .Sh SEE ALSO .Xr flock 1 .Sh HISTORY .Nm was written for the first Network News Transfer Protocol (NNTP) software distribution, released in March 1986. The algorithm was suggested by Peter Honeyman, from work he did on HoneyDanBer UUCP. .Sh AUTHORS .An Erik E. Fair Aq Mt fair@clock.org .Sh BUGS Does not work on NFS or other network file system on different systems because the disparate systems have disjoint PID spaces.
p Cannot handle the case where a lock file was not deleted, the process that created it has exited, and the system has created a new process with the same PID as in the dead lock file. The lock file will appear to be valid even though the process is unrelated to the one that created the lock in the first place. Always remove your lock files after you're done.