persistent process supervision
runtool(8)                         runtools                         runtool(8)

       runtool - run a program in a configured process environment

       runtool  [-hV]  [-0  argv0]  [<-a | -A> argfile] [-c chdir] [-C chroot]
       [-d] [<-e | -E> envfile] [-F fdset] [-L [:]lockfile  |  -P  [:]pidlock]
       [-m  umask] [-R <a|c|d|f|m|o|p|r|s|t>=<num|!>[:...]] [- s] [-S altpath]
       [-u user] [-U user] [-W] [-z secs] program [ args ...]

       runtool modifies a process environment according to its  options,  then
       runs program with any additional args.

       If  program does not contain a ``/'' slash character, runtool will per-
       form a shell-like search for the executable using the PATH variable  in
       the current environment.

       runtool  combines the functions of several individual runtools_intro(8)
       into a single utility.  The corresponding  utility  is  noted  in  each
       option  description,  and  may  be  referenced  there for more complete

       -0 argv0
              runargv0(8).  Sets up program to run with an argv[0] of argv0.

       <-a|-A> argfile
              runargs(8).  Runs program with arguments specified  in  argfile.
              The  -a  form  of  the  option  sets up any arguments taken from
              argfile to preceed any arguments given by args.  The -A form  of
              the  option  inverts  this order, so that any options taken from
              argfile will follow any arguments given by args.

       -c chdir
              chdir(2).  Changes the current working directory to chdir before
              running program.

       -C chroot
              chroot(2).   Sets up the root directory to chroot before running

       -d     rundetach(8).  Detaches from the  controlling  terminal  to  run
              program in the background.

       <-e|-E> envfile
              runenv(8).   Sets  up the environmental variables in the process
              of program according to definitions in envfile.  The -e form  of
              the  option  merges  any  variables  defined in envfile with the
              existing environment.  The -E form of the option defines the new
              environment  exclusively  according  to  envfile and ignores any
              existing environment.  As with runenv(8), the  argument  envfile
              may be either a file or a directory.

       -F fdset
              Sets  up  file descriptors according to the specification fdset,
              given as a single contiguous string in the form:

                     <fd> <op> <target> [: ...]


              fd:    single ascii file descriptor numeral, 0..9

              op:    a single character from the set `<', `>', '+', or '='

                     Depends on op as follows: If op is  redirection  operator
                     '<',  `>',  or  '+', target is an absolute pathname (must
                     begin with `/'), or the special  character  `%'.   Other-
                     wise,  if op is the duplication operator '=', target is a
                     single ascii file descriptor numeral, 0..9, or  the  spe-
                     cial character '!'.

              The  operator  character  `<'  is used to specify redirection of
              input to fd from the file argument given in target.  The  opera-
              tor  characters  `>'  and `+' are used to specify redirection of
              output from fd to the file argument given by  target.   The  `>'
              redirection causes target to be overwritten, while the `+' oper-
              ator appends to any target that may already exist.  The  special
              target  character  `%' may be used as shorthand to represent the
              file /dev/null for either input or output redirection.

              The operator character `=' is used to specify duplication of the
              file descriptor given in fd to the file descriptor given in tar-
              get.  The special target character `!'  is  used  to  close  the
              file descriptor given in fd.

              Normally the fdset argument string will be enclosed in quotes to
              protect it from shell processing.

       -L [:]lockfile
              runlock(8).  Sets up a lockfile before running program.  If  the
              name  of  the lockfile is prefixed by the `:' character, runtool
              will block until a lock can  be  acquired.   Otherwise,  runtool
              will  exit immediately if an existing lock is found on the lock-
              file.  To write the pid of the process into lockfile, use the -P
              option instead.

       -m umask
              umask(2).  Sets up the file creation mask for program.

       -P [:]pidlock
              runlock(8).   Same  as the description for the -L option, except
              that the pid for the process is written into the lock file  pid-

       -R rlims
              runlimit(8).  Sets up the soft resource limits for program where
              rlims is given as a single contiguous string in the form:

                     <rlim> = <value> [: ...]


              rlim:  single character in the set `a', `c', `d', `f', `m', `o',
                     `p', `r', `s', or `t'.

              `=':   the literal character `='.

              value: A  positive  numeric value for the resource limit, or the
                     special character `!' used to specify ``unlimited'', that
                     is,  sets the soft limit equal to the current hard limit.

              The rlim arguments and their meanings are described in the  run-
              limit(8) manual.  Multiple rlimit specifications may be concate-
              nated with the  `:'  character.   Normally  the  rlims  argument
              string  will be enclosed in quotes to protect it from shell pro-

       -s     runsession(8).  Runs program  in  a  separate  session  and  new
              process group.

       -S altpath
              runtool  will  use a PATH-like string given in altpath to search
              for the executable program, rather than within  the  PATH  vari-
              able.   The altpath is only used to search for program, and does
              not affect any PATH variable that may already be set,  nor  does
              altpath persist in the environment of program.

       -u user
              runuid(8).   Sets  up program to run as the user-id and group-id
              of the system account given by user.

       -U user
              runenv(8).  Sets up the two variables UID and GID in  the  envi-
              ronment  of  program with the user-id and group-id of the system
              account given by user.  IMPORTANT:  This  option  does  not,  by
              itself, change the permissions with which program runs.  It only
              sets up a couple of environmental variables that  some  programs
              may use to subsequently change their own permissions.

       -z secs
              runpause(8).  Sleep for secs seconds, or until interrrupted by a
              signal, before running program.  An argument  of  0  will  cause
              runtool to pause indefinitely, or until interrupted by a signal,
              before running program.

       runtool also provides the following standard runtools_intro(8) options:

       -h     Help.  Print a brief usage message to stderr and exit.

       -V     Version.  Print the version number to stderr and exit.

       The order in which runtool applies its operations is independent of the
       order in which the options are given on the command line.  The sequence
       that runtool takes is:

       o   process argfile and argv0

       o   process envfile

       o   process -U user

       o   detach

       o   setsid

       o   acquire lockfile/pidlock

       o   set umask

       o   setup file descriptors according to fdset

       o   setup resource limits

       o   chdir

       o   chroot

       o   setuid

       o   sleep

       o   finally execute program

       When necessary to achieve a different sequence of operations, more than
       one runtool invocation may be combined in an exec  chain,  and/or  com-
       bined  in  an exec chain with one or more of the other purpose-specific
       utilities of the runtools_intro(8) suite.

       runtool 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 runtool

       100    runtool failed because of a usage error, such as an invalid com-
              mand-line  option  or  argument.  In this case, runtool prints a
              brief error message and usage help to stderr on exit.

       111    runtool failed due to some system or resource  error.   In  this
              case,  runtool  prints  a  brief diagnostic message to stderr on

       1-127  program was invoked and failed with its own non-zero  exit  sta-

       Wayne Marshall,

       runtools_intro(8),  runargs(8), runargv0(8), runchoom(8), rundetach(8),
       rundeux(8),    runenv(8),    runfile(8),    runlimit(8),    runlock(8),
       runpause(8), runsession(8), runtrap(8), runuid(8)

runtools-2.07                    January 2013                       runtool(8)