huschi.net

File: coreutils.info,  Node: env invocation,  Next: nice invocation,  Prev: chroot invocation,  Up: Modified command invocation
23.2 `env': Run a command in a modified environment
===================================================
`env' runs a command with a modified environment.  Synopses:
     env [OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...]
     env
   Operands of the form `VARIABLE=VALUE' set the environment variable
VARIABLE to value VALUE.  VALUE may be empty (`VARIABLE=').  Setting a
variable to an empty value is different from unsetting it.  These
operands are evaluated left-to-right, so if two operands mention the
same variable the earlier is ignored.
   Environment variable names can be empty, and can contain any
characters other than `=' and ASCII NUL.  However, it is wise to limit
yourself to names that consist solely of underscores, digits, and ASCII
letters, and that begin with a non-digit, as applications like the
shell do not work well with other names.
   The first operand that does not contain the character `=' specifies
the program to invoke; it is searched for according to the `PATH'
environment variable.  Any remaining arguments are passed as arguments
to that program.  The program should not be a special built-in utility
(*note Special built-in utilities::).
   Modifications to `PATH' take effect prior to searching for COMMAND.
Use caution when reducing `PATH'; behavior is not portable when `PATH'
is undefined or omits key directories such as `/bin'.
   In the rare case that a utility contains a `=' in the name, the only
way to disambiguate it from a variable assignment is to use an
intermediate command for COMMAND, and pass the problematic program name
via ARGS.  For example, if `./prog=' is an executable in the current
`PATH':
     env prog= true # runs 'true', with prog= in environment
     env ./prog= true # runs 'true', with ./prog= in environment
     env -- prog= true # runs 'true', with prog= in environment
     env sh -c '\prog= true' # runs 'prog=' with argument 'true'
     env sh -c 'exec "$@"' sh prog= true # also runs 'prog='
   If no command name is specified following the environment
specifications, the resulting environment is printed.  This is like
specifying the `printenv' program.
   For some examples, suppose the environment passed to `env' contains
`LOGNAME=rms', `EDITOR=emacs', and `PATH=.:/gnubin:/hacks':
   * Output the current environment.
          $ env | LC_ALL=C sort
          EDITOR=emacs
          LOGNAME=rms
          PATH=.:/gnubin:/hacks
   * Run `foo' with a reduced environment, preserving only the original
     `PATH' to avoid problems in locating `foo'.
          env - PATH="$PATH" foo
   * Run `foo' with the environment containing `LOGNAME=rms',
     `EDITOR=emacs', and `PATH=.:/gnubin:/hacks', and guarantees that
     `foo' was found in the file system rather than as a shell built-in.
          env foo
   * Run `nemacs' with the environment containing `LOGNAME=foo',
     `EDITOR=emacs', `PATH=.:/gnubin:/hacks', and `DISPLAY=gnu:0'.
          env DISPLAY=gnu:0 LOGNAME=foo nemacs
   * Attempt to run the program `/energy/--' (as that is the only
     possible path search result); if the command exists, the
     environment will contain `LOGNAME=rms' and `PATH=/energy', and the
     arguments will be `e=mc2', `bar', and `baz'.
          env -u EDITOR PATH=/energy -- e=mc2 bar baz

   The program accepts the following options.  Also see *note Common
options::.  Options must precede operands.
`-0'
`--null'
     Output a zero byte (ASCII NUL) at the end of each line, rather
     than a newline. This option enables other programs to parse the
     output of `env' even when that output would contain data with
     embedded newlines.
`-u NAME'
`--unset=NAME'
     Remove variable NAME from the environment, if it was in the
     environment.
`-'
`-i'
`--ignore-environment'
     Start with an empty environment, ignoring the inherited
     environment.

   Exit status:
     0   if no COMMAND is specified and the environment is output
     125 if `env' itself fails
     126 if COMMAND is found but cannot be invoked
     127 if COMMAND cannot be found
     the exit status of COMMAND otherwise