.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>