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 - (single 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 program 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 environment, 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 program. 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 provision 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-character 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 existing 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 corresponding to the user name acct. Note that this option emphatically does nothing by itself to change the executable permissions of program. It only sets up a couple of environmental variables that may (or may not) be used by the subsequent program 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 command-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 status.

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)