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