--- name: "env" section: "1" platform: "macos" package: "shell_cmds" version: "329" release: "macOS 26.5" platforms: ["linux", "freebsd", "openbsd", "macos"] url: "https://new.carta.tech/env" --- # env(1) set environment and execute command, or print environment ## NAME **env** – set environment and execute command, or print environment ## SYNOPSIS **env** \[**-0iv**\] \[**-u** *name*\] \[*name*=*value* *...*\] **env** \[**-iv**\] \[**-C** *altwd*\] \[**-P** *altpath*\] \[**-S** *string*\] \[**-u** *name*\] \[*name*=*value* *...*\] *utility* \[*argument* *...*\] ## DESCRIPTION The **env** utility executes another *utility* after modifying the environment as specified on the command line. Each *name*=*value* option specifies the setting of an environment variable, *name*, with a value of *value*. All such environment variables are set before the *utility* is executed. The options are as follows: - **-0** End each output line with NUL, not newline. - **-i** Execute the *utility* with only those environment variables specified by *name*=*value* options. The environment inherited by **env** is ignored completely. - **-C** *altwd* Change to the specified alternate working directory before executing the specified *utility* program. - **-P** *altpath* Search the set of directories as specified by *altpath* to locate the specified *utility* program, instead of using the value of the PATH environment variable. - **-S** *string* Split apart the given *string* into multiple strings, and process each of the resulting strings as separate arguments to the **env** utility. The **-S** option recognizes some special character escape sequences and also supports environment-variable substitution, as described below. - **-u** *name* If the environment variable *name* is in the environment, then remove it before processing the remaining options. This is similar to the **unset** command in [sh(1)](/sh/1.md). The value for *name* must not include the ‘=’ character. - **-v** Print verbose information for each step of processing done by the **env** utility. Additional information will be printed if **-v** is specified multiple times. The above options are only recognized when they are specified before any *name*=*value* options. If no *utility* is specified, **env** prints out the names and values of the variables in the environment. Each name/value pair is separated by a new line unless **-0** is specified, in which case name/value pairs are separated by NUL. Both **-0** and *utility* may not be specified together. The **env** utility does not handle values of *utility* which have an equals sign (‘=’) in their name, for obvious reasons. This can easily be worked around by interposing the [command(1)](/command/1.md) utility, which simply executes its arguments; see EXAMPLES below. ### Details of -S (split-string) processing The processing of the **-S** option will split the given *string* into separate arguments based on any space or \ characters found in the *string*. Each of those new arguments will then be treated as if it had been specified as a separate argument on the original **env** command. 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: - **\\c** Ignore the remaining characters in the *string*. This must not appear inside a double-quoted string. - **\\f** Replace with a \ character. - **\\n** Replace with a \ character. - **\\r** Replace with a \ character. - **\\t** Replace with a \ character. - **\\v** Replace with a \ character. - **\\#** Replace with a ‘#’ character. This would be useful when you need a ‘#’ as the first character in one of the arguments created by splitting apart the given *string*. - **\\$** Replace with a ‘$’ character. - **\\\_** 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 *string*. - **\\"** Replace with a \ character. - **\\´** Replace with a \ character. - **\\\\** Replace with a backslash character. The sequences for \ 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. Also, **-S** processing cannot reference the value of the special parameters which are defined by most shells. For instance, **-S** cannot recognize special parameters such as: ‘$\*’, ‘$@’, ‘$#’, ‘$?’ or ‘$$’ if they appear inside the given *string*. ### Use in shell-scripts The **env** utility is often used as the *interpreter* on the first line of interpreted scripts, as described in [execve(2)](/execve/2.md). Note that the ‘#!’ (first line) of an interpreted script is parsed differently on Darwin than it is on many other common systems. The first line will be split into separate arguments based on any whitespace( space or ⟨tab⟩ characters) found in the line. So, if a script named */usr/local/bin/someport* has a first line of: ``` #!/usr/local/bin/php -n -q -dsafe_mode=0 ``` then the */usr/local/bin/php* program will be 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 many other operating system parse the first line of an interpreted script. Notably, the same first line on other systems 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. As a result, uses of the **-S** option like this: ``` #!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0 ``` will behave differently than expected on Darwin, which will instead parse the original version of this first line as if it were executed directly in a shell. ## ENVIRONMENT The **env** utility uses the PATH environment variable to locate the requested *utility* if the name contains no ‘/’ characters, unless the **-P** option has been specified. ## EXIT STATUS The **env** utility exits 0 on success, and \>0 if an error occurs. An exit status of 126 indicates that *utility* was found, but could not be executed. An exit status of 127 indicates that *utility* could not be found. ## EXAMPLES Since the **env** utility is often used as part of the first line of an interpreted script, the following examples show a number of ways that the **env** utility can be useful in scripts. 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 ``` To execute a utility with an equal sign in its name: ``` env name=value ... command foo=bar arg ... ``` ## COMPATIBILITY The **env** utility accepts the **-** option as a synonym for **-i**. ## SEE ALSO [printenv(1)](/printenv/1.md), [sh(1)](/sh/1.md), [execvp(3)](/execvp/3.md), [login.conf(5)](/login.conf/5.md), [environ(7)](/environ/7.md) ## STANDARDS The **env** utility conforms to IEEE Std 1003.1-2001 (“POSIX.1”). The **-0**, **-C**, **-P**, **-S**, **-u** and **-v** options are non-standard extensions supported by FreeBSD, but which may not be available on other operating systems. ## HISTORY The **env** command appeared in 4.4BSD. The **-P**, **-S** and **-v** options were added in FreeBSD 6.0. The **-C** option was added in FreeBSD 14.2. ## BUGS The **env** utility does not take multibyte characters into account when processing the **-S** option, which may lead to incorrect results in some locales.