Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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  op-
       tion  description, and may be referenced	there for more complete	infor-

       -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 ex-
	      isting environment.  The -E form of the option defines  the  new
	      environment exclusively according	to envfile and ignores any ex-
	      isting 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 in-
	      put to fd	from the file argument given in	target.	 The  operator
	      characters `>' and `+' are used to specify redirection of	output
	      from fd to the file argument given by target.  The `>' redirect-
	      ion  causes target to be overwritten, while the `+' operator ap-
	      pends 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 it-
	      self, 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)


Want to link to this manual page? Use this URL:

home | help