# env

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           env — set the environment for command invocation
    


## SYNOPSIS



           env **[** -i**] [**_name_ =_value_**]**... **[**_utility_ **[**_argument_...**]]**
    


## DESCRIPTION



           The _env_ utility shall obtain the current environment, modify it
           according to its arguments, then invoke the utility named by the
           _utility_ operand with the modified environment.
    
           Optional arguments shall be passed to _utility_.
    
           If no _utility_ operand is specified, the resulting environment
           shall be written to the standard output, with one _name_ =_value_ pair
           per line.
    
           If the first argument is **'-'** , the results are unspecified.
    


## OPTIONS



           The _env_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_ , except for
           the unspecified usage of **'-'**.
    
           The following options shall be supported:
    
           **-i** Invoke _utility_ with exactly the environment specified by
                     the arguments; the inherited environment shall be
                     ignored completely.
    


## OPERANDS



           The following operands shall be supported:
    
           _name_ =_value_
                     Arguments of the form _name_ =_value_ shall modify the
                     execution environment, and shall be placed into the
                     inherited environment before the _utility_ is invoked.
    
           _utility_   The name of the utility to be invoked. If the _utility_
                     operand names any of the special built-in utilities in
                     _Section 2.14_ , _Special Built-In Utilities_ , the results
                     are undefined.
    
           _argument_  A string to pass as an argument for the invoked utility.
    


## STDIN



           Not used.
    


## INPUT FILES



           None.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _env_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte as opposed to multi-byte characters in
                     arguments).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    
           _PATH_      Determine the location of the _utility_ , as described in
                     the Base Definitions volume of POSIX.1‐2017, _Chapter 8_ ,
                     _Environment Variables_.  If _PATH_ is specified as a
                     _name_ =_value_ operand to _env_ , the _value_ given shall be used
                     in the search for _utility_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           If no _utility_ operand is specified, each _name_ =_value_ pair in the
           resulting environment shall be written in the form:
    
               "%s=%s\n", <_name_ >, <_value_ >
    
           If the _utility_ operand is specified, the _env_ utility shall not
           write to standard output.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           If _utility_ is invoked, the exit status of _env_ shall be the exit
           status of _utility_ ; otherwise, the _env_ utility shall exit with one
           of the following values:
    
               0   The _env_ utility completed successfully.
    
           1-125   An error occurred in the _env_ utility.
    
             126   The utility specified by _utility_ was found but could not
                   be invoked.
    
             127   The utility specified by _utility_ could not be found.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           The _command_ , _env_ , _nice_ , _nohup_ , _time_ , and _xargs_ utilities have been
           specified to use exit code 127 if an error occurs so that
           applications can distinguish ``failure to find a utility'' from
           ``invoked utility exited with an error indication''. The value 127
           was chosen because it is not commonly used for other meanings;
           most utilities use small values for ``normal error conditions''
           and the values above 128 can be confused with termination due to
           receipt of a signal. The value 126 was chosen in a similar manner
           to indicate that the utility could be found, but not invoked. Some
           scripts produce meaningful error messages differentiating the 126
           and 127 cases. The distinction between exit codes 126 and 127 is
           based on KornShell practice that uses 127 when all attempts to
           _exec_ the utility fail with **[ENOENT]** , and uses 126 when any attempt
           to _exec_ the utility fails for any other reason.
    
           Historical implementations of the _env_ utility use the _execvp_() or
           _execlp_() functions defined in the System Interfaces volume of
           POSIX.1‐2017 to invoke the specified utility; this provides better
           performance and keeps users from having to escape characters with
           special meaning to the shell. Therefore, shell functions, special
           built-ins, and built-ins that are only provided by the shell are
           not found.
    


## EXAMPLES



           The following command:
    
               env -i PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile
    
           invokes the command _mygrep_ with a new _PATH_ value as the only entry
           in its environment other than any variables required by the
           implementation for conformance. In this case, _PATH_ is used to
           locate _mygrep_ , which is expected to reside in **/mybin**.
    


## RATIONALE



           As with all other utilities that invoke other utilities, this
           volume of POSIX.1‐2017 only specifies what _env_ does with standard
           input, standard output, standard error, input files, and output
           files. If a utility is executed, it is not constrained by the
           specification of input and output by _env_.
    
           The **-i** option was added to allow the functionality of the removed
           **-** option in a manner compatible with the Utility Syntax
           Guidelines. It is possible to create a non-conforming environment
           using the **-i** option, as it may remove environment variables
           required by the implementation for conformance. The following will
           preserve these environment variables as well as preserve the _PATH_
           for conforming utilities:
    
               IFS='
               '
               # The preceding value should be <space><tab><newline>.
               # Set IFS to its default value.
    
               set -f
               # disable pathname expansion
    
               \unalias -a
               # Unset all possible aliases.
               # Note that unalias is escaped to prevent an alias
               # being used for unalias.
               # This step is not strictly necessary, since aliases are not inherited,
               # and the ENV environment variable is only used by interactive shells,
               # the only way any aliases can exist in a script is if it defines them
               # itself.
    
               unset -f env getconf
               # Ensure env and getconf are not user functions.
    
               env -i $(getconf V7_ENV) PATH="$(getconf PATH)" command
    
           Some have suggested that _env_ is redundant since the same effect is
           achieved by:
    
               name=value ... utility **[** argument ... **]**
    
           The example is equivalent to _env_ when an environment variable is
           being added to the environment of the command, but not when the
           environment is being set to the given value.  The _env_ utility also
           writes out the current environment if invoked without arguments.
           There is sufficient functionality beyond what the example provides
           to justify inclusion of _env_.
    


## FUTURE DIRECTIONS



           None.
    


* * *