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 lockfile 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 created) 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 command-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 status.

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)