oasis-root

runlock.8 (3848B)

.\" runlock.8
.\" wcm, 2009.09.20 - 2009.12.14
.\" ===
.TH runlock 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runlock \- run another program with a lockfile
.SH SYNOPSIS
.B runlock [\-bpx]
.I lockfile program
.B [
.I args ...
.B ]
.br
.B runlock \-c [\-q]
.I lockfile
.br
.B runlock \-V | \-h
.SH DESCRIPTION
.B runlock
may be used to run a program with a lockfile,
or to check a lockfile for the presence of an existing lock.
.PP
In the first form of the command,
.I lockfile
is a filename and
.I program
is an executable program.
.B runlock
opens
.I lockfile
for writing (creating it if it does not exist),
obtains an exclusive posix advisory lock on
it (see
.BR fcntl (2)),
and then runs
.IR program 
with any remaining arguments.
.PP
If the specified
.I program
name does not contain a ``/'' slash character,
.B runlock
will search for the executable in the search path
defined in the environment by the
.B PATH
variable.
.PP
As long as
.I program
does not itself explicitly release the lock or close the descriptor for
.IR lockfile ,
the lock will remain until the
.I program
exits.
Cooperative programs may test for the existence of a lock on
.I lockfile
to limit the execution of
.I program
to a single instance.
.PP
In the second form of the command (with the
.B \-c
option),
.B runlock
will check
.I lockfile
for an existing lock.
If
.I lockfile
exists
and can be opened for writing,
.B runlock
will report the pid of the process which holds a lock on the file.
Note that the usefulness of this check is limited.
A lock on
.I lockfile
may be acquired or released by another process at anytime.
.SH OPTIONS
.TP
.B \-b
Blocking.
Normally
.B runlock
exits immediately without running
.I program
if an existing lock is found on
.IR lockfile .
When the
.B \-b
option is specified,
.B runlock
waits (blocks) to run
.I program
until it can acquire a lock on
.IR lockfile .
.TP
.B \-c
Check mode.
If this option is specified,
.B runlock
checks
.I lockfile
for the existence of a lock.
.B runlock
exits 0 if no lock is found,
exits 1 if an existing lock is held,
or exits 111 if there is a problem with
.IR lockfile .
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-p
Pid.
Normally
.B runlock
creates a zero-length
.IR lockfile .
If the
.B \-p
option is specified,
.B runlock
writes a human-readable process ID number into the
.IR lockfile .
.TP
.B \-q
Quiet.
In check mode,
the
.B \-q
option suppresses the messages normally printed to stderr.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.TP
.B \-x
Exit no-error.
Normally
.B runlock
prints an error message to stderr and exits nonzero if
.I lockfile
cannot be opened (or created) or locked.
If the
.B \-x
option is specified,
.B runlock
quietly exits zero on these errors.
.SH EXIT STATUS
.B runlock
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runlock
itself.
.TP
100
.B runlock
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runlock
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runlock
failed to acquire a lock due to some system or resource error,
or because a lock was already found on
.I lockfile
(when not using the
.B \-b
option).
In this case,
.B runlock
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlimit (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8)
.\" EOF