freebsd/usr.bin/env/env.1

.\" Copyright (c) 1980, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" From @(#)printenv.1	8.1 (Berkeley) 6/6/93
.\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
.\" $FreeBSD$
.\"
.Dd April 17, 2008
.Dt ENV 1
.Os
.Sh NAME
.Nm env
.Nd set environment and execute command, or print environment
.Sh SYNOPSIS
.Nm
.Op Fl iv
.Op Fl P Ar altpath
.Op Fl S Ar string
.Op Fl u Ar name
.Op Ar name Ns = Ns Ar value ...
.Op Ar utility Op Ar argument ...
.Sh DESCRIPTION
The
.Nm
utility executes another
.Ar utility
after modifying the environment as
specified on the command line.
Each
.Ar name Ns = Ns Ar value
option specifies the setting of an environment variable,
.Ar name ,
with a value of
.Ar value .
All such environment variables are set before the
.Ar utility
is executed.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl i
Execute the
.Ar utility
with only those environment variables specified by
.Ar name Ns = Ns Ar value
options.
The environment inherited
by
.Nm
is ignored completely.
.\"	-P
.It Fl P Ar altpath
Search the set of directories as specified by
.Ar altpath
to locate the specified
.Ar utility
program, instead of using the value of the
.Ev PATH
environment variable.
.\"	-S
.It Fl S Ar string
Split apart the given
.Ar string
into multiple strings, and process each of the resulting strings
as separate arguments to the
.Nm
utility.
The
.Fl S
option recognizes some special character escape sequences and
also supports environment-variable substitution, as described
below.
.\"	-u
.It Fl u Ar name
If the environment variable
.Ar name
is in the environment, then remove it before processing the
remaining options.
This is similar to the
.Ic unset
command in
.Xr sh 1 .
The value for
.Ar name
must not include the
.Ql =
character.
.\"	-v
.It Fl v
Print verbose information for each step of processing done by the
.Nm
utility.
Additional information will be printed if
.Fl v
is specified multiple times.
.El
.Pp
The above options are only recognized when they are specified
before any
.Ar name Ns = Ns Ar value
options.
.Pp
If no
.Ar utility
is specified,
.Nm
prints out the names and values
of the variables in the environment, with one name/value pair per line.
.\"
.Ss Details of Fl S \&Ss (split-string) processing
The processing of the
.Fl S
option will split the given
.Ar string
into separate arguments based on any space or <tab> characters found in the
.Ar string .
Each of those new arguments will then be treated as if it had been
specified as a separate argument on the original
.Nm
command.
.Pp
Spaces and tabs may be embedded in one of those new arguments by using
single
.Pq Dq Li '
or double
.Pq Ql \&"
quotes, or backslashes
.Pq Ql \e .
Single quotes will escape all non-single quote characters, up to
the matching single quote.
Double quotes will escape all non-double quote characters, up to
the matching double quote.
It is an error if the end of the
.Ar string
is reached before the matching quote character.
.Pp
If
.Fl S
would create a new argument that starts with the
.Ql #
character, then that argument and the remainder of the
.Ar string
will be ignored.
The
.Ql \e#
sequence can be used when you want a new argument to start
with a
.Ql #
character, without causing the remainder of the
.Ar string
to be skipped.
.Pp
While processing the
.Ar string
value,
.Fl S
processing will treat certain character combinations as escape
sequences which represent some action to take.
The character escape sequences are in backslash notation.
The characters and their meanings are as follows:
.Pp
.Bl -tag -width indent -offset indent -compact
.It Cm \ec
Ignore the remaining characters in the
.Ar string .
This must not appear inside a double-quoted string.
.It Cm \ef
Replace with a <form-feed> character.
.It Cm \en
Replace with a <new-line> character.
.It Cm \er
Replace with a <carriage return> character.
.It Cm \et
Replace with a <tab> character.
.It Cm \ev
Replace with a <vertical tab> character.
.It Cm \e#
Replace with a
.Ql #
character.
This would be useful when you need a
.Ql #
as the first character in one of the arguments created
by splitting apart the given
.Ar string .
.It Cm \e$
Replace with a
.Ql $
character.
.It Cm \e_
If this is found inside of a double-quoted string, then replace it
with a single blank.
If this is found outside of a quoted string, then treat this as the
separator character between new arguments in the original
.Ar string .
.It Cm \e"
Replace with a <double quote> character.
.It Cm \e\'
Replace with a <single quote> character.
.It Cm \e\e
Replace with a backslash character.
.El
.Pp
The sequences for <single-quote> and backslash are the only sequences
which are recognized inside of a single-quoted string.
The other sequences have no special meaning inside a single-quoted
string.
All escape sequences are recognized inside of a double-quoted string.
It is an error if a single
.Ql \e
character is followed by a character other than the ones listed above.
.Pp
The processing of
.Fl S
also supports substitution of values from environment variables.
To do this, the name of the environment variable must be inside of
.Ql ${} ,
such as:
.Li ${SOMEVAR} .
The common shell syntax of
.Li $SOMEVAR
is not supported.
All values substituted will be the values of the environment variables
as they were when the
.Nm
utility was originally invoked.
Those values will not be checked for any of the escape sequences as
described above.
And any settings of
.Ar name Ns = Ns Ar value
will not effect the values used for substitution in
.Fl S
processing.
.Pp
Also,
.Fl S
processing can not reference the value of the special parameters
which are defined by most shells.
For instance,
.Fl S
can not recognize special parameters such as:
.Ql $* ,
.Ql $@ ,
.Ql $# ,
.Ql $?
or
.Ql $$
if they appear inside the given
.Ar string .
.\"
.Ss Use in shell-scripts
The
.Nm
utility is often used as the
.Ar interpreter
on the first line of interpreted scripts, as
described in
.Xr execve 2 .
.Pp
Note that the way the kernel parses the
.Ql #!
(first line) of an interpreted script has changed as of
.Fx 6.0 .
Prior to that, the
.Fx
kernel would split that first line into separate arguments based
on any whitespace (space or <tab> characters) found in the line.
So, if a script named
.Pa /usr/local/bin/someport
had a first line of:
.Pp
.Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
.Pp
then the
.Pa /usr/local/bin/php
program would have been started with the arguments of:
.Bd -literal -offset indent
arg[0] = '/usr/local/bin/php'
arg[1] = '-n'
arg[2] = '-q'
arg[3] = '-dsafe_mode=0'
arg[4] = '/usr/local/bin/someport'
.Ed
.Pp
plus any arguments the user specified when executing
.Pa someport .
However, this processing of multiple options on the
.Ql #!
line is not the way any other operating system parses the
first line of an interpreted script.
So after a change which was made for
.Fx 6.0
release, that script will result in
.Pa /usr/local/bin/php
being started with the arguments of:
.Bd -literal -offset indent
arg[0] = '/usr/local/bin/php'
arg[1] = '-n -q -dsafe_mode=0'
arg[2] = '/usr/local/bin/someport'
.Ed
.Pp
plus any arguments the user specified.
This caused a significant change in the behavior of a few scripts.
In the case of above script, to have it behave the same way under
.Fx 6.0
as it did under earlier releases, the first line should be
changed to:
.Pp
.Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
.Pp
The
.Nm
utility will be started with the entire line as a single
argument:
.Pp
.Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
.Pp
and then
.Fl S
processing will split that line into separate arguments before
executing
.Pa /usr/local/bin/php .
.\"
.Sh ENVIRONMENT
The
.Nm
utility uses the
.Ev PATH
environment variable to locate the requested
.Ar utility
if the name contains no
.Ql /
characters, unless the
.Fl P
option has been specified.
.Sh EXIT STATUS
.Ex -std
An exit status of 126 indicates that
.Ar utility
was found, but could not be executed.
An exit status of 127 indicates that
.Ar utility
could not be found.
.Sh EXAMPLES
Since the
.Nm
utility is often used as part of the first line of an interpreted script,
the following examples show a number of ways that the
.Nm
utility can be useful in scripts.
.Pp
The kernel processing of an interpreted script does not allow a script
to directly reference some other script as its own interpreter.
As a way around this, the main difference between
.Pp
.Dl #!/usr/local/bin/foo
and
.Dl "#!/usr/bin/env /usr/local/bin/foo"
.Pp
is that the latter works even if
.Pa /usr/local/bin/foo
is itself an interpreted script.
.Pp
Probably the most common use of
.Nm
is to find the correct interpreter for a script, when the interpreter
may be in different directories on different systems.
The following example will find the
.Ql perl
interpreter by searching through the directories specified by
.Ev PATH .
.Pp
.Dl "#!/usr/bin/env perl"
.Pp
One limitation of that example is that it assumes the user's value
for
.Ev PATH
is set to a value which will find the interpreter you want
to execute.
The
.Fl P
option can be used to make sure a specific list of directories is
used in the search for
.Ar utility .
Note that the
.Fl S
option is also required for this example to work correctly.
.Pp
.Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
.Pp
The above finds
.Ql perl
only if it is in
.Pa /usr/local/bin
or
.Pa /usr/bin .
That could be combined with the present value of
.Ev PATH ,
to provide more flexibility.
Note that spaces are not required between the
.Fl S
and
.Fl P
options:
.Pp
.Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
.Sh COMPATIBILITY
The
.Nm
utility accepts the
.Fl
option as a synonym for
.Fl i .
.Sh SEE ALSO
.Xr printenv 1 ,
.Xr sh 1 ,
.Xr execvp 3 ,
.Xr environ 7
.Sh STANDARDS
The
.Nm
utility conforms to
.St -p1003.1-2001 .
The
.Fl P , S , u
and
.Fl v
options are non-standard extensions supported by
.Fx ,
but which may not be available on other operating systems.
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.4 .
The
.Fl P , S
and
.Fl v
options were added in
.Fx 6.0 .
.Sh BUGS
The
.Nm
utility does not handle values of
.Ar utility
which have an equals sign
.Pq Ql =
in their name, for obvious reasons.
.Pp
The
.Nm
utility does not take multibyte characters into account when
processing the
.Fl S
option, which may lead to incorrect results in some locales.