.TH ENV 1
.SH NAME
env \- set environment for command
.SH SYNOPSIS
.B env
.RB [ \-ia ]
.RI [ name\fB=\fIvalue "] ..."
.RI [ utility
.RI [ argument "...]]"
.SH DESCRIPTION
.B Env
modifies its environment according to the
.IB name = value
arguments, and executes
.I utility
with the given arguments and the modified environment.
.PP
If no utility is specified then the modified environment is printed as
.IB name = value
strings, one per line.
.SH OPTIONS
.TP
.B \-i
Use exactly the environment specified by the arguments; the inherited
environment is ignored.
.TP
.B \-a
Specify all arguments for the utility, i.e. the first of the arguments is
used as
.BR "argv[0]" ,
the program name.  Normally the program name is
.I utility
itself.
.SH ENVIRONMENT
.TP 8n
.B PATH
The path used to find utility.  It is as modified by
.BR env ,
i.e.
.B not
the inherited
.BR PATH .
.SH "SEE ALSO"
.BR sh (1),
.BR execvp (3),
.BR environ (5).
.SH DIAGNOSTICS
The return code is
.B 0
after successfully printing the environment,
.B 1
on an error within
.BR env ,
.B 126
if the
.I utility
could not be executed, or
.B 127
if
.I utility
could not be found.  Appropriate diagnostic messages are printed on standard
error.
If
.I utility
can be executed then it replaces
.BR env ,
so the return code is then the return code of
.IR utility .
.SH NOTES
When run from the standard shell
.B env
is only useful with options or without arguments.  Otherwise the shell can
do exactly what
.B env
can do, simply omit the word "env" on the command line.
.PP
One interesting use of
.B env
is with #! on the first line of a script to forge a PATH search for an
interpreter.  For example:
.PP
.RS
#!/usr/bin/env perl
.RE
.PP
This will find the Perl interpreter if it is within the user's PATH.  Most
UNIX-like systems have
.B env
in /usr/bin, but
.B perl
may be anywhere.
.SH AUTHOR
Kees J. Bot <kjb@cs.vu.nl>