Lots of stuff.

[misc] / locking.1

diff --git a/locking.1 b/locking.1
new file mode 100644 (file)
index 0000000..04842e7
--- /dev/null
+++ b/locking.1
@@ -0,0 +1,107 @@
+.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.
+.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@nsict.org>