FreeBSD Manual Pages
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 perform 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 de- scription, 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 in- verts 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 pro- gram. -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 op- tion merges any variables defined in envfile with the existing envi- ronment. The -E form of the option defines the new environment ex- clusively 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 `%'. Otherwise, if op is the duplication operator '=', target is a single ascii file de- scriptor numeral, 0..9, or the special character '!'. The operator character `<' is used to specify redirection of input to fd from the file argument given in target. The operator charac- ters `>' 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 `+' operator appends to any tar- get 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 target. The special target character `!' is used to close the file descrip- tor 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 immedi- ately if an existing lock is found on the lockfile. 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 pidlock. -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 spe- cial 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 concatenated with the `:' character. Normally the rlims argument string will be enclosed in quotes to protect it from shell processing. -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 variable. 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 environment 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 run- ning 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 or- der in which the options are given on the command line. The sequence that runtool takes is: * process argfile and argv0 * process envfile * process -U user * detach * setsid * acquire lockfile/pidlock * set umask * setup file descriptors according to fdset * setup resource limits * chdir * chroot * setuid * sleep * 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 combined 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 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), runlock(8), runpause(8), runsession(8), runtrap(8), runuid(8) runtools-2.07 January 2013 runtool(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERATING SEQUENCE | EXIT STATUS | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=runtool&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>