runtool(8) runtools runtool(8)
NAME
runtool - run a program in a configured process environment
SYNOPSIS
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 ...]
DESCRIPTION
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.
OPTIONS
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
information.
-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
program.
-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> [: ...]
Where:
fd: single ascii file descriptor numeral, 0..9
op: a single character from the set `<', `>', '+', or '='
target:
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-
lock.
-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> [: ...]
Where:
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-
cessing.
-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.
OPERATING SEQUENCE
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.
EXIT STATUS
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
itself.
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
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), runlock(8),
runpause(8), runsession(8), runtrap(8), runuid(8)
runtools-2.07 January 2013 runtool(8)