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 exi