Unix/Linux Go Back    


Linux 2.6 - man page for env (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ENV(P)				    POSIX Programmer's Manual				   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 argu-
       ments, 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, Sec-
       tion 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       -i     Invoke utility with exactly the environment specified by the arguments; the  inher-
	      ited 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 spe-
	      cial 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, Inter-
	      nationalization 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  interna-
	      tionalization 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  argu-
	      ments).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic 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 util-
	      ity.

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;  other-
       wise, 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  util-
       ity"  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 con-
       strained 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 envi-
       ronment 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					   ENV(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:28 AM.