runenv(8) runtools runenv(8)
NAME
runenv - run a program with a modified environment
SYNOPSIS
runenv [-hV] [-i] [-U acct ] newenv program [ args ... ]
DESCRIPTION
runenv starts program with a modified environment. As distinct from
common versions of env(1), modifications are applied only within the
environment of program; the environment of runenv itself is not
affected.
Modifications for the new environment are specified in the argument
newenv, which is either a file or a directory. If newenv is a - (sin-
gle dash), runenv reads the modifications from standard input as
described for a file.
The argument program may be either a pathname or a filename. If pro-
gram contains a ``/'' (slash) character, it is considered a pathname
and runenv will attempt to invoke it directly. Otherwise, runenv will
perform a shell-like search for program within the directories defined
in the PATH variable of the runtime environment of runenv.
If the argument newenv is a file:
The file newenv is opened and read line by line. A line in the form of
k=v is interpreted as an environmental variable, k, defined with a
value of v. If the variable k does not exist in the current environ-
ment, k=v will be added to the environment of program. If the variable
k does exist in the current environment, its value will be replaced by
v in the environment of program.
A line in the form of k only, without =v, specifies that any existing
variable k will be deleted (unset) from the environment of program.
All names and values read from file are trimmed of leading and trailing
whitespace. Empty lines and lines beginning with ``#'' are ignored.
If the argument newenv is a directory:
Each file k in the directory newenv is interpreted as an environmental
variable k=v, where k is the name of the file, and v is read from the
first line of the file. As above, if the variable k does not exist in
the current environment, k=v will be added to the environment of pro-
gram. If the variable k does exist in the current environment, its
value will be replaced by v in the environment of program.
If the file k is empty, then any existing variable k will be deleted
(unset) from the environment of program.
Filenames in the directory newenv that begin with ``.'' are ignored,
and filenames should not contain ``=''. The values read from files in
newenv are trimmed of leading and trailing whitespace. No special pro-
vision is made for commenting files, except to note that any text
occuring after the first line is ignored.
Escape sequences:
Whether newenv is a file or directory, a limited number of two-charac-
ter escape sequences are supported within value definitions:
``\n'' is changed to newline
``\t'' is changed to tab
``\_'' (backslash + underscore) is changed to single space
``\\'' is changed to single backslash
These escape sequences make it possible to embed newlines in values,
and provide a way to retain leading and trailing whitespace. Any other
``\'' sequences found within a value are left verbatim.
OPTIONS
-h Help. Display brief usage message and exit.
-i Ignore existing environment. Normally runenv modifies the
existing environment. If the -i option is specified, any exist-
ing environment is ignored and only new environment definitions
are passed to program.
-U acct
UID/GID. A few programs look specifically for environmental
variables named UID and GID. The -U option may be used as a
convenient way to set these variables with the uid/gid corre-
sponding to the user name acct. Note that this option emphati-
cally does nothing by itself to change the executable permis-
sions of program. It only sets up a couple of environmental
variables that may (or may not) be used by the subsequent pro-
gram according to its own design. To affect the actual set-
user-ID permissions of program, see runuid(8).
-V Version. Report the version number and exit.
EXIT STATUS
runenv 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 runenv
itself.
100 runenv failed because of a usage error, such as an invalid com-
mand-line option or argument. In this case, runenv prints a
brief error message and usage help to stderr on exit.
111 runenv failed due to some system or resource error. In this
case, runenv 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), runfile(8), runlimit(8), runlock(8), runpause(8),
runsession(8), runtool(8), runtrap(8), runuid(8)
runtools-2.07 January 2013 runenv(8)