man/man1/env.1

   1 .TH ENV 1
   2 .SH NAME
   3 env \- set environment for command
   4 .SH SYNOPSIS
   5 .B env
   6 .RB [ \-ia ]
   7 .RI [ name\fB=\fIvalue "] ..."
   8 .RI [ utility
   9 .RI [ argument "...]]"
  10 .B printenv
  11 .RB [ \-ia ]
  12 .RI [ name\fB=\fIvalue "] ..."
  13 .RI [ utility
  14 .RI [ argument "...]]"
  15 .SH DESCRIPTION
  16 .B Env
  17 modifies its environment according to the
  18 .IB name = value
  19 arguments, and executes
  20 .I utility
  21 with the given arguments and the modified environment.
  22 .PP
  23 If no utility is specified then the modified environment is printed as
  24 .IB name = value
  25 strings, one per line.
  26 .PP
  27 .B printenv
  28 is identical to env in every way and is included for backward compatibility
  29 .SH OPTIONS
  30 .TP
  31 .B \-i
  32 Use exactly the environment specified by the arguments; the inherited
  33 environment is ignored.
  34 .TP
  35 .B \-a
  36 Specify all arguments for the utility, i.e. the first of the arguments is
  37 used as
  38 .BR "argv[0]" ,
  39 the program name.  Normally the program name is
  40 .I utility
  41 itself.
  42 .SH ENVIRONMENT
  43 .TP 8n
  44 .B PATH
  45 The path used to find utility.  It is as modified by
  46 .BR env ,
  47 i.e.
  48 .B not
  49 the inherited
  50 .BR PATH .
  51 .SH "SEE ALSO"
  52 .BR sh (1),
  53 .BR execvp (3),
  54 .BR environ (5).
  55 .SH DIAGNOSTICS
  56 The return code is
  57 .B 0
  58 after successfully printing the environment,
  59 .B 1
  60 on an error within
  61 .BR env ,
  62 .B 126
  63 if the
  64 .I utility
  65 could not be executed, or
  66 .B 127
  67 if
  68 .I utility
  69 could not be found.  Appropriate diagnostic messages are printed on standard
  70 error.
  71 If
  72 .I utility
  73 can be executed then it replaces
  74 .BR env ,
  75 so the return code is then the return code of
  76 .IR utility .
  77 .SH NOTES
  78 When run from the standard shell
  79 .B env
  80 is only useful with options or without arguments.  Otherwise the shell can
  81 do exactly what
  82 .B env
  83 can do, simply omit the word "env" on the command line.
  84 .PP
  85 One interesting use of
  86 .B env
  87 is with #! on the first line of a script to forge a PATH search for an
  88 interpreter.  For example:
  89 .PP
  90 .RS
  91 #!/usr/bin/env perl
  92 .RE
  93 .PP
  94 This will find the Perl interpreter if it is within the user's PATH.  Most
  95 UNIX-like systems have
  96 .B env
  97 in /usr/bin, but
  98 .B perl
  99 may be anywhere.
 100 .SH AUTHOR
 101 Kees J. Bot <kjb@cs.vu.nl>