[apple/shell_cmds.git] / shlock / shlock.1

.\"	$NetBSD: shlock.1,v 1.2 1997/10/19 23:08:43 lukem 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 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
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.
Commit	Line	Data
44bd5ea7 A	1	.\" $NetBSD: shlock.1,v 1.2 1997/10/19 23:08:43 lukem Exp $
	2	.\"
	3	.Dd June 29, 1997
	4	.Dt SHLOCK 1
	5	.Os
	6	.Sh NAME
	7	.Nm shlock
	8	.Nd create or verify a lock file for shell scripts
	9	.Sh SYNOPSIS
	10	.Nm
	11	.Fl f
	12	.Ar lockfile
	13	.Op Fl p Ar PID
	14	.Op Fl u
	15	.Op Fl v
	16	.Sh DESCRIPTION
	17	The
	18	.Nm
	19	command can create or verify a lock file on behalf of a shell or
	20	other script program.
	21	When it attempts to create a lock file, if one already exists,
	22	.Nm
	23	verifies that it is or is not valid.
	24	If valid,
	25	.Nm
	26	will exit with a non-zero exit code.
	27	If invalid,
	28	.Nm
	29	will remove the lock file, and
	30	create a new one.
	31	.Pp
	32	.Nm
	33	uses the
	34	.Xr rename 2
	35	system call to make the final target lock file, which is an atomic
	36	operation (i.e. "dot locking", so named for this mechanism's original
	37	use for locking system mailboxes).
	38	It puts the process ID ("PID") from the command line into the
	39	requested lock file.
	40	.Pp
	41	.Nm
	42	verifies that an extant lock file is still valid by
	43	using
	44	.Xr kill 2
	45	with a zero signal to check for the existence of the process that
	46	holds the lock.
	47	.Pp
	48	The
	49	.Fl f
	50	argument with
	51	.Ar lockfile
	52	is always required.
	53	.Pp
	54	The
	55	.Fl p
	56	option with
	57	.Ar PID
	58	is given when the program is to create a lock file; when absent,
	59	.Nm
	60	will simply check for the validity of the lock file.
	61	.Pp
	62	The
	63	.Fl u
	64	option causes
65	.Nm
66	to read and write the PID as a binary pid_t, instead of as ASCII,
67	to be compatible with the locks created by UUCP.
68	.Pp
69	The
70	.Fl v
71	option causes
72	.Nm
73	to be verbose about what it is doing.
74	.Sh RETURN VALUES
75	A zero exit code indicates a valid lock file.
76	.Sh EXAMPLES
77	.Ss BOURNE SHELL
78	.Bd -literal
79	#!/bin/sh
80	lckfile=/tmp/foo.lock
81	if shlock -f ${lckfile} -p $$
82	then
83	# do what required the lock
84	rm ${lckfile}
85	else
86	echo Lock ${lckfile} already held by `cat ${lckfile}`
87	fi
88	.Ed
89	.Ss C SHELL
90	.Bd -literal
91	#!/bin/csh -f
92	set lckfile=/tmp/foo.lock
93	shlock -f ${lckfile} -p $$
94	if ($status == 0) then
95	# do what required the lock
96	rm ${lckfile}
97	else
98	echo Lock ${lckfile} already held by `cat ${lckfile}`
99	endif
100	.Ed
101
102	.Pp
103	The examples assume that the filesystem where the lock file is to
104	be created is writeable by the user, and has space available.
105	.Sh HISTORY
106	.Nm
107	was written for the first Network News Transfer Protocol (NNTP)
108	software distribution, released in March 1986.
109	The algorithm was suggested by Peter Honeyman,
110	from work he did on HoneyDanBer UUCP.
111	.Sh AUTHOR
112	Erik E. Fair <fair@clock.org>
113	.Sh BUGS
114	Does not work on NFS or other network filesystem on different
115	systems because the disparate systems have disjoint PID spaces.
116	.Pp
117	Cannot handle the case where a lock file was not deleted, the
118	process that created it has exited, and the system has created a
119	new process with the same PID as in the dead lock file.
120	The lock file will appear to be valid even though the process is
121	unrelated to the one that created the lock in the first place.
122	Always remove your lock files after you're done.