9182eb7285
NetBSD-current, into the NetBSD Packages Collection.
The shlock 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, shlock verifies that it is or is not
valid. If valid, shlock will exit with a non-zero exit code. If
invalid, shlock will re- move the lock file, and create a new one.
shlock uses the rename(2) system call to make the final target lock
file, which is an atomic operation (i.e. "dot locking", so named for
this mech- anism's original use for locking system mailboxes). It
puts the process ID ("PID") from the command line into the requested
lock file.
shlock verifies that an extant lock file is still valid by using
kill(2) with a zero signal to check for the existence of the process
that holds the lock.
This package is only for Solaris and Linux platforms at present.
121 lines
2.8 KiB
Groff
121 lines
2.8 KiB
Groff
.\" $NetBSD: shlock.1,v 1.1.1.1 2002/01/15 13:20:28 agc Exp $
|
|
.\"
|
|
.Dd June 29, 1997
|
|
.Dt SHLOCK 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm shlock
|
|
.Nd create or verify a lock file for shell scripts
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl f
|
|
.Ar lockfile
|
|
.Op Fl p Ar PID
|
|
.Op Fl u
|
|
.Op Fl d
|
|
.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.
|
|
.Pp
|
|
.Nm
|
|
uses the
|
|
.Xr rename 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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
The
|
|
.Fl f
|
|
argument with
|
|
.Ar lockfile
|
|
is always required.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fl d
|
|
option causes
|
|
.Nm
|
|
to be verbose about what it is doing.
|
|
.Sh EXIT STATUS
|
|
A zero exit code indicates a valid lock file.
|
|
.Sh EXAMPLES
|
|
.Ss BOURNE SHELL
|
|
.Bd -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
|
|
.Bd -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
|
|
.Pp
|
|
The examples assume that the filesystem where the lock file is to
|
|
be created is writeable by the user, and has space available.
|
|
.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 fair@clock.org
|
|
.Sh BUGS
|
|
Does not work on NFS or other network filesystem on different
|
|
systems because the disparate systems have disjoint PID spaces.
|
|
.Pp
|
|
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.
|