env(P)                                                   env(P)





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  envi-
       ronment  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 spec-
              ified 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 internationaliza-
              tion  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 cate-
              gories.)

       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 mes-
              sages 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 simi-
       lar 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 dis-
       tinction  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 rea-
       son.

       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 spe-
       cial 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  com-
       mand,  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 suf-
       ficient 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 Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute 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.open-
       group.org/unix/online.html .



POSIX                         2003                       env(P)
