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

.\"	$NetBSD: shlock.1,v 1.11 2008/04/30 13:11:01 martin Exp $
.\"
.\" Copyright (c) 2006 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Erik E. Fair.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.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
.Op Fl du
.Op Fl p Ar PID
.Fl f
.Ar lockfile
.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 link 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 d
option causes
.Nm
to be verbose about what it is doing.
.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.
.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 file system where the lock file is to
be created is writable 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 file system 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
f14763b6 A	1	.\" $NetBSD: shlock.1,v 1.11 2008/04/30 13:11:01 martin Exp $
	2	.\"
	3	.\" Copyright (c) 2006 The NetBSD Foundation, Inc.
	4	.\" All rights reserved.
	5	.\"
	6	.\" This code is derived from software contributed to The NetBSD Foundation
	7	.\" by Erik E. Fair.
	8	.\"
	9	.\" Redistribution and use in source and binary forms, with or without
	10	.\" modification, are permitted provided that the following conditions
	11	.\" are met:
	12	.\" 1. Redistributions of source code must retain the above copyright
	13	.\" notice, this list of conditions and the following disclaimer.
	14	.\" 2. Redistributions in binary form must reproduce the above copyright
	15	.\" notice, this list of conditions and the following disclaimer in the
	16	.\" documentation and/or other materials provided with the distribution.
	17	.\"
	18	.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
	19	.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
	20	.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	21	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
	22	.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	23	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	24	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	25	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	26	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	27	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	28	.\" POSSIBILITY OF SUCH DAMAGE.
44bd5ea7 A	29	.\"
	30	.Dd June 29, 1997
	31	.Dt SHLOCK 1
	32	.Os
	33	.Sh NAME
	34	.Nm shlock
	35	.Nd create or verify a lock file for shell scripts
	36	.Sh SYNOPSIS
	37	.Nm
f14763b6 A	38	.Op Fl du
f14763b6 A	39	.Op Fl p Ar PID
44bd5ea7 A	40	.Fl f
44bd5ea7 A	41	.Ar lockfile
44bd5ea7 A	42	.Sh DESCRIPTION
	43	The
	44	.Nm
	45	command can create or verify a lock file on behalf of a shell or
	46	other script program.
	47	When it attempts to create a lock file, if one already exists,
	48	.Nm
	49	verifies that it is or is not valid.
	50	If valid,
	51	.Nm
	52	will exit with a non-zero exit code.
	53	If invalid,
	54	.Nm
f14763b6	55	will remove the lock file, and
44bd5ea7 A	56	create a new one.
	57	.Pp
	58	.Nm
	59	uses the
f14763b6	60	.Xr link 2
44bd5ea7 A	61	system call to make the final target lock file, which is an atomic
	62	operation (i.e. "dot locking", so named for this mechanism's original
	63	use for locking system mailboxes).
	64	It puts the process ID ("PID") from the command line into the
	65	requested lock file.
	66	.Pp
	67	.Nm
	68	verifies that an extant lock file is still valid by
	69	using
	70	.Xr kill 2
	71	with a zero signal to check for the existence of the process that
	72	holds the lock.
	73	.Pp
	74	The
f14763b6 A	75	.Fl d
	76	option causes
	77	.Nm
	78	to be verbose about what it is doing.
	79	.Pp
	80	The
44bd5ea7 A	81	.Fl f
	82	argument with
	83	.Ar lockfile
	84	is always required.
	85	.Pp
	86	The
	87	.Fl p
	88	option with
	89	.Ar PID
	90	is given when the program is to create a lock file; when absent,
	91	.Nm
	92	will simply check for the validity of the lock file.
	93	.Pp
	94	The
	95	.Fl u
	96	option causes
	97	.Nm
	98	to read and write the PID as a binary pid_t, instead of as ASCII,
	99	to be compatible with the locks created by UUCP.
f14763b6	100	.Sh EXIT STATUS
44bd5ea7 A	101	A zero exit code indicates a valid lock file.
	102	.Sh EXAMPLES
	103	.Ss BOURNE SHELL
	104	.Bd -literal
	105	#!/bin/sh
	106	lckfile=/tmp/foo.lock
	107	if shlock -f ${lckfile} -p $$
	108	then
	109	# do what required the lock
	110	rm ${lckfile}
	111	else
	112	echo Lock ${lckfile} already held by `cat ${lckfile}`
	113	fi
	114	.Ed
	115	.Ss C SHELL
	116	.Bd -literal
	117	#!/bin/csh -f
	118	set lckfile=/tmp/foo.lock
	119	shlock -f ${lckfile} -p $$
	120	if ($status == 0) then
	121	# do what required the lock
	122	rm ${lckfile}
	123	else
	124	echo Lock ${lckfile} already held by `cat ${lckfile}`
	125	endif
	126	.Ed
44bd5ea7	127	.Pp
f14763b6 A	128	The examples assume that the file system where the lock file is to
f14763b6 A	129	be created is writable by the user, and has space available.
44bd5ea7 A	130	.Sh HISTORY
	131	.Nm
	132	was written for the first Network News Transfer Protocol (NNTP)
	133	software distribution, released in March 1986.
	134	The algorithm was suggested by Peter Honeyman,
	135	from work he did on HoneyDanBer UUCP.
f14763b6 A	136	.Sh AUTHORS
f14763b6 A	137	.An Erik E. Fair Aq fair@clock.org
44bd5ea7	138	.Sh BUGS
f14763b6	139	Does not work on NFS or other network file system on different
44bd5ea7 A	140	systems because the disparate systems have disjoint PID spaces.
	141	.Pp
	142	Cannot handle the case where a lock file was not deleted, the
	143	process that created it has exited, and the system has created a
	144	new process with the same PID as in the dead lock file.
	145	The lock file will appear to be valid even though the process is
	146	unrelated to the one that created the lock in the first place.
	147	Always remove your lock files after you're done.