Initial import of Erik E. Fair's shlock utility, with sources taken from

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.

6 files changed, 526 insertions, 0 deletions

diff --git a/pkgtools/shlock/DESCR b/pkgtools/shlock/DESCR
new file mode 100644
index 00000000000..c1c7ffd861d
--- /dev/null
+++ b/pkgtools/shlock/DESCR
@@ -0,0 +1,15 @@
+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.
diff --git a/pkgtools/shlock/Makefile b/pkgtools/shlock/Makefile
new file mode 100644
index 00000000000..9314f86d999
--- /dev/null
+++ b/pkgtools/shlock/Makefile
@@ -0,0 +1,38 @@
+# $NetBSD: Makefile,v 1.1.1.1 2002/01/15 13:20:27 agc Exp $
+#
+
+DISTNAME=	shlock-20020114
+CATEGORIES=	pkgtools sysutils
+MASTER_SITES=	#
+
+MAINTAINER=	packages@netbsd.org
+#HOMEPAGE=
+COMMENT=	shell utility to perform dot-locking
+
+ONLY_FOR_PLATFORM=	SunOS-*-* Linux-*-*
+
+EXTRACT_ONLY=	#empty
+WRKSRC=		${WRKDIR}
+NO_CHECKSUM=	#defined
+MANCOMPRESSED_IF_MANZ=	yes
+PLIST_SRC=	${WRKDIR}/PLIST
+BUILD_DEFS+=	MANINSTALL
+
+MAKE_ENV+=	BINDIR=${LOCALBASE}/bin MANDIR=${LOCALBASE}/man
+
+post-extract:
+	@for FILE in Makefile shlock.c shlock.1; do			\
+		${CP} ${FILESDIR}/$$FILE ${WRKSRC};			\
+	done
+
+pre-install:
+	@${RM} -f ${PLIST_SRC}
+	@${CP} ${PKGDIR}/PLIST ${PLIST_SRC}
+	@if [ -n "${MANINSTALL:Mcatinstall}" ]; then			\
+		${ECHO} man/cat1/shlock.0 >> ${PLIST_SRC};		\
+	fi
+	@if [ -n "${MANINSTALL:Mmaninstall}" ]; then			\
+		${ECHO} man/man1/shlock.1 >> ${PLIST_SRC};		\
+	fi
+
+.include "../../mk/bsd.pkg.mk"
diff --git a/pkgtools/shlock/PLIST b/pkgtools/shlock/PLIST
new file mode 100644
index 00000000000..47c6ed31acf
--- /dev/null
+++ b/pkgtools/shlock/PLIST
@@ -0,0 +1,2 @@
+@comment $NetBSD: PLIST,v 1.1.1.1 2002/01/15 13:20:27 agc Exp $
+bin/shlock
diff --git a/pkgtools/shlock/files/Makefile b/pkgtools/shlock/files/Makefile
new file mode 100644
index 00000000000..1a39d6ebf24
--- /dev/null
+++ b/pkgtools/shlock/files/Makefile
@@ -0,0 +1,5 @@
+#	$NetBSD: Makefile,v 1.1.1.1 2002/01/15 13:20:28 agc Exp $
+
+PROG=   shlock
+
+.include <bsd.prog.mk>
diff --git a/pkgtools/shlock/files/shlock.1 b/pkgtools/shlock/files/shlock.1
new file mode 100644
index 00000000000..dd5928f4761
--- /dev/null
+++ b/pkgtools/shlock/files/shlock.1
@@ -0,0 +1,121 @@
+.\"	$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.
diff --git a/pkgtools/shlock/files/shlock.c b/pkgtools/shlock/files/shlock.c
new file mode 100644
index 00000000000..78b9b822e2e
--- /dev/null
+++ b/pkgtools/shlock/files/shlock.c
@@ -0,0 +1,345 @@
+/*	$NetBSD: shlock.c,v 1.1.1.1 2002/01/15 13:20:28 agc Exp $	*/
+
+/*
+** Program to produce reliable locks for shell scripts.
+** Algorithm suggested by Peter Honeyman, January 1984,
+** in connection with HoneyDanBer UUCP.
+**
+** I tried extending this to handle shared locks in November 1987,
+** and ran into to some fundamental problems:
+**
+**	Neither 4.3 BSD nor System V have an open(2) with locking,
+**	so that you can open a file and have it locked as soon as
+**	it's real; you have to make two system calls, and there's
+**	a race...
+**
+**	When removing dead process id's from a list in a file,
+**	you need to truncate the file (you don't want to create a
+**	new one; see above); unfortunately for the portability of
+**	this program, only 4.3 BSD has ftruncate(2).
+**
+** Erik E. Fair <fair@ucbarpa.berkeley.edu>, November 8, 1987
+**
+** Extensions for UUCP style locks (i.e. pid is an int in the file,
+** rather than an ASCII string). Also fix long standing bug with
+** full file systems and temporary files.
+**
+** Erik E. Fair <fair@apple.com>, November 12, 1989
+**
+** ANSIfy the code somewhat to make gcc -Wall happy with the code.
+** Submit to NetBSD
+**
+** Erik E. Fair <fair@clock.org>, May 20, 1997
+*/
+
+#include <sys/types.h>
+#include <sys/file.h>
+#include <fcntl.h>			/* Needed on hpux */
+#include <stdio.h>
+#include <signal.h>
+#include <errno.h>
+#include <string.h>
+#include <unistd.h>
+#include <stdlib.h>
+
+#define	LOCK_SET	0
+#define	LOCK_FAIL	1
+
+#define	LOCK_GOOD	0
+#define	LOCK_BAD	1
+
+#define	FAIL		(-1)
+
+#define	TRUE	1
+#define	FALSE	0
+
+int	Debug = FALSE;
+char	*Pname;
+const char USAGE[] = "%s: USAGE: shlock -f file -p pid [-d][-u]\n";
+const char E_unlk[] = "%s: unlink(%s): %s\n";
+const char E_open[] = "%s: open(%s): %s\n";
+
+#define	dprintf	if (Debug) printf
+
+/*
+** Prototypes to make the ANSI compilers happy
+** Didn't lint used to do type and argument checking?
+** (and wasn't that sufficient?)
+*/
+
+#ifdef __STDC__
+/* the following is in case you need to make the prototypes go away. */
+#define _P(x)	x
+
+char	*xtmpfile _P((char *, pid_t, int));
+int	p_exists _P((pid_t));
+int	cklock _P((char *, int));
+int	mklock _P((char *, pid_t, int));
+void	bad_usage _P((void));
+int	main _P((int, char **));
+#endif /* __STDC__ */
+
+/*
+** Create a temporary file, all ready to lock with.
+** The file arg is so we get the filename right, if he
+** gave us a full path, instead of using the current directory
+** which might not be in the same filesystem.
+*/
+char *
+xtmpfile(file, pid, uucpstyle)
+char	*file;
+pid_t	pid;
+int	uucpstyle;
+{
+	int	fd;
+	int	len;
+	char	*cp, buf[BUFSIZ];
+	static char	tempname[BUFSIZ];
+
+	sprintf(buf, "shlock%ld", (u_long)getpid());
+	if ((cp = strrchr(strcpy(tempname, file), '/')) != (char *)NULL) {
+		*++cp = '\0';
+		(void) strcat(tempname, buf);
+	} else
+		(void) strcpy(tempname, buf);
+	dprintf("%s: temporary filename: %s\n", Pname, tempname);
+
+	sprintf(buf, "%ld\n", (u_long)pid);
+	len = strlen(buf);
+openloop:
+	if ((fd = open(tempname, O_RDWR|O_CREAT|O_EXCL, 0644)) < 0) {
+		switch(errno) {
+		case EEXIST:
+			dprintf("%s: file %s exists already.\n",
+				Pname, tempname);
+			if (unlink(tempname) < 0) {
+				fprintf(stderr, E_unlk,
+					Pname, tempname, strerror(errno));
+				return((char *)NULL);
+			}
+			/*
+			** Further profanity
+			*/
+			goto openloop;
+		default:
+			fprintf(stderr, E_open,
+				Pname, tempname, strerror(errno));
+			return((char *)NULL);
+		}
+	}
+
+	/*
+	** Write the PID into the temporary file before attempting to link
+	** to the actual lock file. That way we have a valid lock the instant
+	** the link succeeds.
+	*/
+	if (uucpstyle ?
+		(write(fd, &pid, sizeof(pid)) != sizeof(pid)) :
+		(write(fd, buf, len) < 0))
+	{
+		fprintf(stderr, "%s: write(%s,%ld): %s\n",
+			Pname, tempname, (u_long)pid, strerror(errno));
+		(void) close(fd);
+		if (unlink(tempname) < 0) {
+			fprintf(stderr, E_unlk,
+				Pname, tempname, strerror(errno));
+		}
+		return((char *)NULL);
+	}
+	(void) close(fd);
+	return(tempname);
+}
+
+/*
+** Does the PID exist?
+** Send null signal to find out.
+*/
+int
+p_exists(pid)
+pid_t	pid;
+{
+	dprintf("%s: process %ld is ", Pname, (u_long)pid);
+	if (pid <= 0) {
+		dprintf("invalid\n");
+		return(FALSE);
+	}
+	if (kill(pid, 0) < 0) {
+		switch(errno) {
+		case ESRCH:
+			dprintf("dead\n");
+			return(FALSE);	/* pid does not exist */
+		case EPERM:
+			dprintf("alive\n");
+			return(TRUE);	/* pid exists */
+		default:
+			dprintf("state unknown: %s\n", strerror(errno));
+			return(TRUE);	/* be conservative */
+		}
+	}
+	dprintf("alive\n");
+	return(TRUE);	/* pid exists */
+}
+
+/*
+** Check the validity of an existing lock file.
+**
+**	Read the PID out of the lock
+**	Send a null signal to determine whether that PID still exists
+**	Existence (or not) determines the validity of the lock.
+**
+**	Two bigs wins to this algorithm:
+**
+**	o	Locks do not survive crashes of either the system or the
+**			application by any appreciable period of time.
+**
+**	o	No clean up to do if the system or application crashes.
+**
+*/
+int
+cklock(file, uucpstyle)
+char	*file;
+int	uucpstyle;
+{
+	int	fd = open(file, O_RDONLY);
+	ssize_t len;
+	pid_t	pid;
+	char	buf[BUFSIZ];
+
+	dprintf("%s: checking extant lock <%s>\n", Pname, file);
+	if (fd < 0) {
+		if (errno != ENOENT)
+			fprintf(stderr, E_open, Pname, file, strerror(errno));
+		return(TRUE);	/* might or might not; conservatism */
+	}
+
+	if (uucpstyle ?
+		((len = read(fd, &pid, sizeof(pid))) != sizeof(pid)) :
+		((len = read(fd, buf, sizeof(buf))) <= 0))
+	{
+		close(fd);
+		dprintf("%s: lock file format error\n", Pname);
+		return(FALSE);
+	}
+	close(fd);
+	buf[len + 1] = '\0';
+	return(p_exists(uucpstyle ? pid : atoi(buf)));
+}
+
+int
+mklock(file, pid, uucpstyle)
+char	*file;
+pid_t	pid;
+int	uucpstyle;
+{
+	char	*tmp;
+	int	retcode = FALSE;
+
+	dprintf("%s: trying lock <%s> for process %ld\n", Pname, file,
+	    (u_long)pid);
+	if ((tmp = xtmpfile(file, pid, uucpstyle)) == (char *)NULL)
+		return(FALSE);
+
+linkloop:
+	if (link(tmp, file) < 0) {
+		switch(errno) {
+		case EEXIST:
+			dprintf("%s: lock <%s> already exists\n", Pname, file);
+			if (cklock(file, uucpstyle)) {
+				dprintf("%s: extant lock is valid\n", Pname);
+				break;
+			} else {
+				dprintf("%s: lock is invalid, removing\n",
+					Pname);
+				if (unlink(file) < 0) {
+					fprintf(stderr, E_unlk,
+						Pname, file, strerror(errno));
+					break;
+				}
+			}
+			/*
+			** I hereby profane the god of structured programming,
+			** Edsgar Dijkstra
+			*/
+			goto linkloop;
+		default:
+			fprintf(stderr, "%s: link(%s, %s): %s\n",
+				Pname, tmp, file, strerror(errno));
+			break;
+		}
+	} else {
+		dprintf("%s: got lock <%s>\n", Pname, file);
+		retcode = TRUE;
+	}
+	if (unlink(tmp) < 0) {
+		fprintf(stderr, E_unlk, Pname, tmp, strerror(errno));
+	}
+	return(retcode);
+}
+
+void
+bad_usage()
+{
+	fprintf(stderr, USAGE, Pname);
+	exit(LOCK_FAIL);
+}
+
+int
+main(ac, av)
+int	ac;
+char	*av[];
+{
+	int	x;
+	char	*file = (char *)NULL;
+	pid_t	pid = 0;
+	int	uucpstyle = FALSE;	/* indicating UUCP style locks */
+	int	only_check = TRUE;	/* don't make a lock */
+
+	Pname = ((Pname = strrchr(av[0], '/')) ? Pname + 1 : av[0]);
+
+	for(x = 1; x < ac; x++) {
+		if (av[x][0] == '-') {
+			switch(av[x][1]) {
+			case 'u':
+				uucpstyle = TRUE;
+				break;
+			case 'd':
+				Debug = TRUE;
+				break;
+			case 'p':
+				if (strlen(av[x]) > 2) {
+					pid = atoi(&av[x][2]);
+				} else {
+					if (++x >= ac) {
+						bad_usage();
+					}
+					pid = atoi(av[x]);
+				}
+				only_check = FALSE;	/* wants one */
+				break;
+			case 'f':
+				if (strlen(av[x]) > 2) {
+					file = &av[x][2];
+				} else {
+					if (++x >= ac) {
+						bad_usage();
+					}
+					file = av[x];
+				}
+				break;
+			default:
+				fprintf(stderr, USAGE, Pname);
+				exit(LOCK_FAIL);
+			}
+		}
+	}
+
+	if (file == (char *)NULL || (!only_check && pid <= 0)) {
+		bad_usage();
+	}
+
+	if (only_check) {
+		exit(cklock(file, uucpstyle) ? LOCK_GOOD : LOCK_BAD);
+	}
+
+	exit(mklock(file, pid, uucpstyle) ? LOCK_SET : LOCK_FAIL);
+}