[misc] / locking.1

.TH "locking" 1 "11 May 2003" "Mark Wooding" "Toys"
.SH NAME
locking \- run a program with a lock held
.
.SH SYNOPSIS
.B locking
.RB [ \-cfwx ]
.RB [ \-p
.IR realprog ]
.RB [ \-t
.IR time ]
.I file
.I prog
.IR args ...
.
.SH "DESCRIPTION"
The
.B locking
program opens and locks
.I file
while it runs some program
.IR prog .
This is handy in shell scripts and (particularly) crontab entries.  It
was initially written to ensure that news fetches only occurred if the
previous one had completed.
.PP
The program uses
.BR fcntl (2)-style
locking.  It will not leave stale locks lying around: the lock is
released if
.I prog
or the
.B locking
program itself quits for any reason.
.PP
The following options are supported:
.TP
.B "\-h, \-\-help"
Write a full help message to stdout, and exit zero.
.TP
.B "\-v, \-\-version"
Write the version number to stdout, and exit zero.
.TP
.B "\-u, \-\-usage"
Write a brief usage message to stdout, and exit zero.
.TP
.BR "\-c, \-\-" [ "no\-" ] "create"
Create
.I file
if it doesn't already exist.  The file is created with mode 666 as
modified by the process's umask in the usual way.  This is the default
behaviour.  The options
.B +c
or
.B \-\-no\-create
will cause
.B locking
to fail if the file does not already exist.
.TP
.BR "\-f, \-\-" [ "no\-" ] "fail"
Fail (report an error and exit nonzero) if
.I file
is already locked.  The default behaviour is to exit successfully
without running
.IR prog .
.TP
.BR "\-w, \-\-" [ "no\-" ] "wait"
Wait for the lock on
.I file
to become available.  The default behaviour is to give up immediately.
.TP
.BR "\-x, \-\-" [ "no\-" ] "exclusive"
Obtain an exclusive lock on the file.  This is the default.  The options
.B +x
or
.B \-\-no\-exclusive
obtain a non-exclusive lock on the file instead.
.TP
.BI "\-p, \-\-program=" realprog
Run the program
.IR realprog ,
passing it
.I prog
as its first argument.  The default behaviour is to run
.IR prog .
.TP
.BI "\-t, \-\-timeout=" time
Wait for
.I time
(an integer, optionally followed by
.RB ` d ',
.RB ` h ',
.RB ` m ',
or
.RB ` s '
for days, hours, minutes or seconds, respectively) for the lock to
become available, and then give up.  This only makes sense with the
.B \-\-wait
option, so that is turned on automatically.
.PP
It is safe to unlink or atomically replace the lockfile while holding
the lock, though these actions will release the lock immediately.  To
safely delete the lockfile, for example, run
.IP
.B "locking lock rm lock"
.PP
Similarly, a file can be updated safely by
.IP
.nf
.ft B
locking file sh -c \e
\h'8m'"update-file file >file.new && mv file.new file"
.fi
.ft R
.SH "BUGS"
The
.B locking
program messes with alarms.  It tries to put them back the way it found
them, but may get things wrong.
.
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
f342fce2	1	.TH "locking" 1 "11 May 2003" "Mark Wooding" "Toys"
	2	.SH NAME
	3	locking \- run a program with a lock held
	4	.
	5	.SH SYNOPSIS
	6	.B locking
	7	.RB [ \-cfwx ]
	8	.RB [ \-p
	9	.IR realprog ]
	10	.RB [ \-t
	11	.IR time ]
	12	.I file
	13	.I prog
	14	.IR args ...
	15	.
	16	.SH "DESCRIPTION"
	17	The
	18	.B locking
	19	program opens and locks
	20	.I file
	21	while it runs some program
	22	.IR prog .
	23	This is handy in shell scripts and (particularly) crontab entries. It
	24	was initially written to ensure that news fetches only occurred if the
	25	previous one had completed.
	26	.PP
	27	The program uses
	28	.BR fcntl (2)-style
	29	locking. It will not leave stale locks lying around: the lock is
	30	released if
	31	.I prog
	32	or the
	33	.B locking
	34	program itself quits for any reason.
	35	.PP
	36	The following options are supported:
	37	.TP
	38	.B "\-h, \-\-help"
	39	Write a full help message to stdout, and exit zero.
	40	.TP
	41	.B "\-v, \-\-version"
	42	Write the version number to stdout, and exit zero.
	43	.TP
	44	.B "\-u, \-\-usage"
	45	Write a brief usage message to stdout, and exit zero.
	46	.TP
	47	.BR "\-c, \-\-" [ "no\-" ] "create"
	48	Create
	49	.I file
	50	if it doesn't already exist. The file is created with mode 666 as
	51	modified by the process's umask in the usual way. This is the default
	52	behaviour. The options
	53	.B +c
	54	or
	55	.B \-\-no\-create
	56	will cause
	57	.B locking
	58	to fail if the file does not already exist.
	59	.TP
	60	.BR "\-f, \-\-" [ "no\-" ] "fail"
	61	Fail (report an error and exit nonzero) if
	62	.I file
	63	is already locked. The default behaviour is to exit successfully
	64	without running
65	.IR prog .
66	.TP
67	.BR "\-w, \-\-" [ "no\-" ] "wait"
68	Wait for the lock on
69	.I file
70	to become available. The default behaviour is to give up immediately.
71	.TP
72	.BR "\-x, \-\-" [ "no\-" ] "exclusive"
73	Obtain an exclusive lock on the file. This is the default. The options
74	.B +x
75	or
76	.B \-\-no\-exclusive
77	obtain a non-exclusive lock on the file instead.
78	.TP
79	.BI "\-p, \-\-program=" realprog
80	Run the program
81	.IR realprog ,
82	passing it
83	.I prog
84	as its first argument. The default behaviour is to run
85	.IR prog .
86	.TP
87	.BI "\-t, \-\-timeout=" time
88	Wait for
89	.I time
90	(an integer, optionally followed by
91	.RB ` d ',
92	.RB ` h ',
93	.RB ` m ',
94	or
95	.RB ` s '
96	for days, hours, minutes or seconds, respectively) for the lock to
97	become available, and then give up. This only makes sense with the
98	.B \-\-wait
99	option, so that is turned on automatically.
ed1b4ef8 MW	100	.PP
	101	It is safe to unlink or atomically replace the lockfile while holding
	102	the lock, though these actions will release the lock immediately. To
	103	safely delete the lockfile, for example, run
	104	.IP
	105	.B "locking lock rm lock"
	106	.PP
	107	Similarly, a file can be updated safely by
	108	.IP
	109	.nf
	110	.ft B
	111	locking file sh -c \e
	112	\h'8m'"update-file file >file.new && mv file.new file"
	113	.fi
	114	.ft R
f342fce2	115	.SH "BUGS"
	116	The
	117	.B locking
	118	program messes with alarms. It tries to put them back the way it found
	119	them, but may get things wrong.
	120	.
	121	.SH "AUTHOR"
71d8432e	122	Mark Wooding, <mdw@distorted.org.uk>