Permalink
Browse files

program to make lock files for shell scripts

  • Loading branch information...
1 parent a2bca40 commit 7451c680a38861a2804798731b67c46771959a36 fair committed Aug 6, 1997
Showing with 465 additions and 0 deletions.
  1. +3 −0 usr.bin/shlock/Makefile
  2. +120 −0 usr.bin/shlock/shlock.1
  3. +342 −0 usr.bin/shlock/shlock.c
View
@@ -0,0 +1,3 @@
+PROG= shlock
+
+.include <bsd.prog.mk>
View
@@ -0,0 +1,120 @@
+.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 shlock
+.Fl f
+.Ar lockfile
+.Op Fl p Ar PID
+.Op Fl u
+.Op Fl v
+.Sh DESCRIPTION
+The
+.Nm 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,
+.Nm shlock
+verifies that it is or is not valid.
+If valid,
+.Nm shlock
+will exit with a non-zero exit code.
+If invalid,
+.Nm shlock
+will remove the lock file, and
+create a new one.
+.Pp
+.Nm shlock
+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 shlock
+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 shlock
+will simply check for the validity of the lock file.
+.Pp
+The
+.Fl u
+option causes
+.Nm shlock
+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 shlock
+to be verbose about what it is doing.
+.Sh RETURN VALUES
+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 shlock
+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.
Oops, something went wrong.

0 comments on commit 7451c68

Please sign in to comment.