oasis-root

runenv.8 (5261B)

.\" runenv.8
.\" wcm, 2009.09.17 - 2009.12.15
.\" ===
.TH runenv 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runenv \- run a program with a modified environment
.SH SYNOPSIS
.B runenv [\-hV] [\-i] [\-U
.I acct
.B ]
.I newenv
.I program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runenv
starts
.I program
with a modified environment.
As distinct from common versions of
.BR env (1),
modifications are applied only within the environment of
.IR program;
the environment of
.B runenv
itself is not affected.
.PP
Modifications for the new environment are specified in the argument
.IR newenv ,
which is either a file or a directory.
If
.I newenv
is a
.B \-
(single dash),
.B runenv
reads the modifications from standard input as described for a file.
.PP
The argument
.I program
may be either a pathname or a filename.
If
.I program
contains a ``/'' (slash) character,
it is considered a pathname and
.B runenv
will attempt to invoke it directly.
Otherwise,
.B runenv
will perform a shell-like search for
.I program
within the directories defined in the PATH
variable of the runtime environment of
.BR runenv .
.PP
If the argument
.I newenv
is a file:
.PP
The file
.I newenv
is opened and read line by line.
A line in the form of
.I k=v
is interpreted as an environmental variable,
.IR k ,
defined with a value of
.IR v .
If the variable
.I k
does not exist in the current environment,
.I k=v
will be added to the environment of
.IR program .
If the variable
.I k 
does exist in the current environment,
its value will be replaced by
.I v
in the environment of
.IR program .
.PP
A line in the form of
.I k
only, without
.IR =v ,
specifies that any existing variable
.I k
will be deleted (unset) from the environment of
.IR program .
.PP
All names and values read from
.I file
are trimmed of leading and trailing whitespace.
Empty lines and lines beginning with ``#'' are ignored.
.PP
If the argument
.I newenv
is a directory:
.PP
Each file
.I k
in the directory
.I newenv
is interpreted as an environmental variable
.IR k=v ,
where
.I k
is the name of the file,
and
.I v
is read from the first line of the file.
As above, if the variable
.I k
does not exist in the current environment,
.I k=v
will be added to the environment of
.IR program .
If the variable
.I k
does exist in the current environment,
its value will be replaced by
.I v
in the environment of
.IR program .
.PP
If the file
.I k
is empty,
then any existing variable
.I k
will be deleted (unset) from the environment of
.IR program .
.PP
Filenames in the directory
.I newenv 
that begin with ``.'' are ignored,
and filenames should not contain ``=''.
The values read from files in
.I 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.
.PP
Escape sequences:
.PP
Whether
.I newenv
is a file or directory,
a limited number of two-character escape sequences are supported within
value definitions:
.TP
``\\n''
is changed to newline
.TP
``\\t''
is changed to tab
.TP
``\\_'' (backslash + underscore) is changed to single space
.TP
``\\\\''
is changed to single backslash
.PP
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.
.SH OPTIONS
.TP
.B \-h
Help.
Display brief usage message and exit.
.TP
.B \-i
Ignore existing environment.
Normally
.B runenv
modifies the existing environment.
If the
.B \-i
option is specified,
any existing environment is ignored and only new environment definitions
are passed to
.IR program .
.TP
.B \-U acct
UID/GID.
A few programs look specifically for environmental variables named
.I UID
and
.IR GID .
The
.B \-U
option may be used as a convenient way to set these variables with the uid/gid
corresponding to the user name
.IR acct .
Note that this option emphatically does nothing by itself
to change the executable permissions of
.IR program .
It only sets up a couple of environmental variables
that
may (or may not) be used by the subsequent
.IR program
according to its own design.
To affect the actual set-user-ID permissions of
.IR program ,
see
.BR runuid (8).
.TP
.B \-V
Version.
Report the version number and exit.
.SH EXIT STATUS
.B runenv
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runenv
itself.
.TP
100
.B runenv
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runenv
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runenv
failed due to some system or resource error.
In this case,
.B runenv
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runfile (8),
.BR runlimit (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8)
..\" EOF: runenv.8