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