Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ENV(1)			FreeBSD	General	Commands Manual			ENV(1)

     env -- set	environment and	execute	command, or print environment

     env [-iv] [-P altpath] [-S	string]	[-u name] [name=value ...]
	 [utility [argument ...]]

     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:

     -i	     Execute the utility with only those environment variables speci-
	     fied by name=value	options.  The environment inherited by env is
	     ignored completely.

     -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 simi-
	     lar to the	unset command in sh(1).	 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, with	one name/value pair per	line.

   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 <tab> characters found in the string.
     Each of those new arguments will then be treated as if it had been	speci-
     fied 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 char-
     acter 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 <form-feed> character.
	   \n	   Replace with	a <new-line> character.
	   \r	   Replace with	a <carriage return> character.
	   \t	   Replace with	a <tab>	character.
	   \v	   Replace with	a <vertical tab> character.
	   \#	   Replace with	a `#' character.  This would be	useful when
		   you need a `#' as the first character in one	of the argu-
		   ments 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	char-
		   acter between new arguments in the original string.
	   \"	   Replace with	a <double quote> character.
	   \'	   Replace with	a <single quote> character.
	   \\	   Replace with	a backslash character.

     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 environ-
     ment 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 origi-
     nally 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 can not reference the value of	the special parameters
     which are defined by most shells.	For instance, -S can not 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).

     Note that the way the kernel parses the `#!' (first line) of an inter-
     preted script has changed as of FreeBSD 6.0.  Prior to that, the FreeBSD
     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 FreeBSD 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 FreeBSD 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 argu-

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

     and then -S processing will split that line into separate arguments
     before executing /usr/local/bin/php.

     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.

     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 exe-
     cuted.  An	exit status of 127 indicates that utility could	not be found.

     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/bin/env /usr/local/bin/foo

     is	that the latter	works even if /usr/local/bin/foo is itself an inter-
     preted 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' inter-
     preter 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	exe-
     cute.  The	-P option can be used to make sure a specific list of directo-
     ries 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 flexi-
     bility.  Note that	spaces are not required	between	the -S and -P options:

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

     The env utility accepts the - option as a synonym for -i.

     printenv(1), sh(1), execvp(3), environ(7)

     The env utility conforms to IEEE Std 1003.1-2001 (``POSIX.1'').  The -P,
     -S, -u and	-v options are non-standard extensions supported by FreeBSD,
     but which may not be available on other operating systems.

     The env command appeared in 4.4BSD.  The -P, -S and -v options were added
     in	FreeBSD	6.0.

     The env utility does not handle values of utility which have an equals
     sign (`=')	in their name, for obvious reasons.

     The env utility does not take multibyte characters	into account when pro-
     cessing the -S option, which may lead to incorrect	results	in some

FreeBSD	8.4-stable		April 17, 2008		    FreeBSD 8.4-stable


Want to link to this manual page? Use this URL:

home | help