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.

OPTIONS

       The env utility shall conform to the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       Section 12.2, Utility Syntax Guidelines.

       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  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  IEEE Std 1003.1-2001,  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  IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001 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 mygrep xyz myfile

       invokes the command mygrep with a new PATH value as the only entry in its environment.  In
       this case, PATH is used to locate mygrep, which then must reside in /mybin.

RATIONALE

       As   with   all   other   utilities   that   invoke   other   utilities,  this  volume  of
       IEEE Std 1003.1-2001 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 withdrawn - option in  a  manner
       compatible with the Utility Syntax Guidelines.

       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.

SEE ALSO

       Parameters and Variables , Special Built-In Utilities

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .