53b435482d
It turns out that currently mandoc(1) is not handling Fl in Ss correctly (maybe it never was). Let's just replace "Fl S \&Ss ..." with "-S ...". After all, this subsection title is stylized anyway, so Fl is not that helpful. MFC after: 2 weeks
522 lines
13 KiB
Groff
522 lines
13 KiB
Groff
.\" 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 24, 2020
|
|
.Dt ENV 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm env
|
|
.Nd set environment and execute command, or print environment
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl 0iv
|
|
.Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
|
|
.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 0
|
|
End each output line with NUL, not newline.
|
|
.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.
|
|
.\" -L | -U
|
|
.It Fl L | Fl U Ar user Ns Op / Ns Ar class
|
|
Add the environment variable definitions from
|
|
.Xr login.conf 5
|
|
for the specified user and login class to the environment, after
|
|
processing any
|
|
.Fl i
|
|
or
|
|
.Fl u
|
|
options, but before processing any
|
|
.Ar name Ns = Ns Ar value
|
|
options.
|
|
If
|
|
.Fl L
|
|
is used, only the system-wide
|
|
.Pa /etc/login.conf.db
|
|
file is read; if
|
|
.Fl U
|
|
is used, then the specified user's
|
|
.Pa ~/.login_conf
|
|
is read as well.
|
|
The user may be specified by name or by uid.
|
|
.\" -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.
|
|
Each name/value pair is separated by a new line unless
|
|
.Fl 0
|
|
is specified, in which case name/value pairs are separated by NUL.
|
|
Both
|
|
.Fl 0
|
|
and
|
|
.Ar utility
|
|
may not be specified together.
|
|
.\"
|
|
.Ss Details of -S (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 cannot reference the value of the special parameters
|
|
which are defined by most shells.
|
|
For instance,
|
|
.Fl S
|
|
cannot 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 login.conf 5 ,
|
|
.Xr environ 7
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility conforms to
|
|
.St -p1003.1-2001 .
|
|
The
|
|
.Fl 0 , L , P , S , U , 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 .
|
|
The
|
|
.Fl 0 , L
|
|
and
|
|
.Fl U
|
|
options were added in
|
|
.Fx 13.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.
|