CONTENTS

SYNOPSIS

DESCRIPTION

The options are as follows:

The above options are only recognized when they are specified before any name = value options.

Spaces and tabs may be embedded in one of those new arguments by using single ("’") or double (‘"’) quotes, or backslashes (‘\’). 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 string is reached before the matching quote character.

If -S would create a new argument that starts with the ‘#’ character, then that argument and the remainder of the string will be ignored. The ‘\#’ sequence can be used when you want a new argument to start with a ‘#’ character, without causing the remainder of the string to be skipped.

While processing the string value, -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:

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 ‘\’ character is followed by a character other than the ones listed above.

The processing of -S also supports substitution of values from environment variables. To do this, the name of the environment variable must be inside of ‘${}’, such as: ${SOMEVAR}. The common shell syntax of $SOMEVAR is not supported. All values substituted will be the values of the environment variables as they were when the env utility was originally invoked. Those values will not be checked for any of the escape sequences as described above. And any settings of name = value will not effect the values used for substitution in -S processing.

Note that the way the kernel parses the ‘#!’ (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 /usr/local/bin/someport had a first line of:

"#!/usr/local/bin/php -n -q -dsafe_mode=0"

then the /usr/local/bin/php program would have been started with the arguments of:
arg[0] = ’/usr/local/bin/php’
arg[1] = ’-n’
arg[2] = ’-q’
arg[3] = ’-dsafe_mode=0’
arg[4] = ’/usr/local/bin/someport’

plus any arguments the user specified when executing someport. However, this processing of multiple options on the ‘#!’ 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 /usr/local/bin/php being started with the arguments of:
arg[0] = ’/usr/local/bin/php’
arg[1] = ’-n -q -dsafe_mode=0’
arg[2] = ’/usr/local/bin/someport’

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:

"#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"

The env utility will be started with the entire line as a single argument:

"arg[1] = ’-S /usr/local/bin/php -n -q -dsafe_mode=0’"

EXIT STATUS

EXAMPLES

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

#!/usr/local/bin/foo

and

"#!/usr/bin/env /usr/local/bin/foo"

is that the latter works even if /usr/local/bin/foo is itself an interpreted script.

Probably the most common use of env 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 ‘perl’ interpreter by searching through the directories specified by PATH.

"#!/usr/bin/env perl"

One limitation of that example is that it assumes the user’s value for PATH is set to a value which will find the interpreter you want to execute. The -P option can be used to make sure a specific list of directories is used in the search for utility. Note that the -S option is also required for this example to work correctly.

"#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"

The above finds ‘perl’ only if it is in /usr/local/bin or /usr/bin. That could be combined with the present value of PATH, to provide more flexibility. Note that spaces are not required between the -S and -P options:

"#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"

SEE ALSO

STANDARDS

HISTORY

BUGS