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)