123 lines
2.8 KiB
Groff
123 lines
2.8 KiB
Groff
.\" $NetBSD: shlock.1,v 1.3 2000/09/04 07:35:19 kleink 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 v
|
|
.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 v
|
|
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 AUTHOR
|
|
Erik E. Fair <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.
|