/usr.bin/env/env.1
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 482 lines · 482 code · 0 blank · 0 comment · 0 complexity · 6c9bab9d8f34c972199ea6e7dc320ed1 MD5 · raw file
- .\" 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.
- .\" 4. 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.