/usr.bin/env/env.1

  1.\" Copyright (c) 1980, 1990, 1993
  2.\"	The Regents of the University of California.  All rights reserved.
  3.\"
  4.\" This code is derived from software contributed to Berkeley by
  5.\" the Institute of Electrical and Electronics Engineers, Inc.
  6.\" Redistribution and use in source and binary forms, with or without
  7.\" modification, are permitted provided that the following conditions
  8.\" are met:
  9.\" 1. Redistributions of source code must retain the above copyright
 10.\"    notice, this list of conditions and the following disclaimer.
 11.\" 2. Redistributions in binary form must reproduce the above copyright
 12.\"    notice, this list of conditions and the following disclaimer in the
 13.\"    documentation and/or other materials provided with the distribution.
 14.\" 4. Neither the name of the University nor the names of its contributors
 15.\"    may be used to endorse or promote products derived from this software
 16.\"    without specific prior written permission.
 17.\"
 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 28.\" SUCH DAMAGE.
 29.\"
 30.\" From @(#)printenv.1	8.1 (Berkeley) 6/6/93
 31.\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
 32.\" $FreeBSD$
 33.\"
 34.Dd April 17, 2008
 35.Dt ENV 1
 36.Os
 37.Sh NAME
 38.Nm env
 39.Nd set environment and execute command, or print environment
 40.Sh SYNOPSIS
 41.Nm
 42.Op Fl iv
 43.Op Fl P Ar altpath
 44.Op Fl S Ar string
 45.Op Fl u Ar name
 46.Op Ar name Ns = Ns Ar value ...
 47.Op Ar utility Op Ar argument ...
 48.Sh DESCRIPTION
 49The
 50.Nm
 51utility executes another
 52.Ar utility
 53after modifying the environment as
 54specified on the command line.
 55Each
 56.Ar name Ns = Ns Ar value
 57option specifies the setting of an environment variable,
 58.Ar name ,
 59with a value of
 60.Ar value .
 61All such environment variables are set before the
 62.Ar utility
 63is executed.
 64.Pp
 65The options are as follows:
 66.Bl -tag -width indent
 67.It Fl i
 68Execute the
 69.Ar utility
 70with only those environment variables specified by
 71.Ar name Ns = Ns Ar value
 72options.
 73The environment inherited
 74by
 75.Nm
 76is ignored completely.
 77.\"	-P
 78.It Fl P Ar altpath
 79Search the set of directories as specified by
 80.Ar altpath
 81to locate the specified
 82.Ar utility
 83program, instead of using the value of the
 84.Ev PATH
 85environment variable.
 86.\"	-S
 87.It Fl S Ar string
 88Split apart the given
 89.Ar string
 90into multiple strings, and process each of the resulting strings
 91as separate arguments to the
 92.Nm
 93utility.
 94The
 95.Fl S
 96option recognizes some special character escape sequences and
 97also supports environment-variable substitution, as described
 98below.
 99.\"	-u
100.It Fl u Ar name
101If the environment variable
102.Ar name
103is in the environment, then remove it before processing the
104remaining options.
105This is similar to the
106.Ic unset
107command in
108.Xr sh 1 .
109The value for
110.Ar name
111must not include the
112.Ql =
113character.
114.\"	-v
115.It Fl v
116Print verbose information for each step of processing done by the
117.Nm
118utility.
119Additional information will be printed if
120.Fl v
121is specified multiple times.
122.El
123.Pp
124The above options are only recognized when they are specified
125before any
126.Ar name Ns = Ns Ar value
127options.
128.Pp
129If no
130.Ar utility
131is specified,
132.Nm
133prints out the names and values
134of the variables in the environment, with one name/value pair per line.
135.\"
136.Ss Details of Fl S Ss (split-string) processing
137The processing of the
138.Fl S
139option will split the given
140.Ar string
141into separate arguments based on any space or <tab> characters found in the
142.Ar string .
143Each of those new arguments will then be treated as if it had been
144specified as a separate argument on the original
145.Nm
146command.
147.Pp
148Spaces and tabs may be embedded in one of those new arguments by using
149single
150.Pq Dq Li '
151or double
152.Pq Ql \&"
153quotes, or backslashes
154.Pq Ql \e .
155Single quotes will escape all non-single quote characters, up to
156the matching single quote.
157Double quotes will escape all non-double quote characters, up to
158the matching double quote.
159It is an error if the end of the
160.Ar string
161is reached before the matching quote character.
162.Pp
163If
164.Fl S
165would create a new argument that starts with the
166.Ql #
167character, then that argument and the remainder of the
168.Ar string
169will be ignored.
170The
171.Ql \e#
172sequence can be used when you want a new argument to start
173with a
174.Ql #
175character, without causing the remainder of the
176.Ar string
177to be skipped.
178.Pp
179While processing the
180.Ar string
181value,
182.Fl S
183processing will treat certain character combinations as escape
184sequences which represent some action to take.
185The character escape sequences are in backslash notation.
186The characters and their meanings are as follows:
187.Pp
188.Bl -tag -width indent -offset indent -compact
189.It Cm \ec
190Ignore the remaining characters in the
191.Ar string .
192This must not appear inside a double-quoted string.
193.It Cm \ef
194Replace with a <form-feed> character.
195.It Cm \en
196Replace with a <new-line> character.
197.It Cm \er
198Replace with a <carriage return> character.
199.It Cm \et
200Replace with a <tab> character.
201.It Cm \ev
202Replace with a <vertical tab> character.
203.It Cm \e#
204Replace with a
205.Ql #
206character.
207This would be useful when you need a
208.Ql #
209as the first character in one of the arguments created
210by splitting apart the given
211.Ar string .
212.It Cm \e$
213Replace with a
214.Ql $
215character.
216.It Cm \e_
217If this is found inside of a double-quoted string, then replace it
218with a single blank.
219If this is found outside of a quoted string, then treat this as the
220separator character between new arguments in the original
221.Ar string .
222.It Cm \e"
223Replace with a <double quote> character.
224.It Cm \e\'
225Replace with a <single quote> character.
226.It Cm \e\e
227Replace with a backslash character.
228.El
229.Pp
230The sequences for <single-quote> and backslash are the only sequences
231which are recognized inside of a single-quoted string.
232The other sequences have no special meaning inside a single-quoted
233string.
234All escape sequences are recognized inside of a double-quoted string.
235It is an error if a single
236.Ql \e
237character is followed by a character other than the ones listed above.
238.Pp
239The processing of
240.Fl S
241also supports substitution of values from environment variables.
242To do this, the name of the environment variable must be inside of
243.Ql ${} ,
244such as:
245.Li ${SOMEVAR} .
246The common shell syntax of
247.Li $SOMEVAR
248is not supported.
249All values substituted will be the values of the environment variables
250as they were when the
251.Nm
252utility was originally invoked.
253Those values will not be checked for any of the escape sequences as
254described above.
255And any settings of
256.Ar name Ns = Ns Ar value
257will not effect the values used for substitution in
258.Fl S
259processing.
260.Pp
261Also,
262.Fl S
263processing can not reference the value of the special parameters
264which are defined by most shells.
265For instance,
266.Fl S
267can not recognize special parameters such as:
268.Ql $* ,
269.Ql $@ ,
270.Ql $# ,
271.Ql $?
272or
273.Ql $$
274if they appear inside the given
275.Ar string .
276.\"
277.Ss Use in shell-scripts
278The
279.Nm
280utility is often used as the
281.Ar interpreter
282on the first line of interpreted scripts, as
283described in
284.Xr execve 2 .
285.Pp
286Note that the way the kernel parses the
287.Ql #!
288(first line) of an interpreted script has changed as of
289.Fx 6.0 .
290Prior to that, the
291.Fx
292kernel would split that first line into separate arguments based
293on any whitespace (space or <tab> characters) found in the line.
294So, if a script named
295.Pa /usr/local/bin/someport
296had a first line of:
297.Pp
298.Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
299.Pp
300then the
301.Pa /usr/local/bin/php
302program would have been started with the arguments of:
303.Bd -literal -offset indent
304arg[0] = '/usr/local/bin/php'
305arg[1] = '-n'
306arg[2] = '-q'
307arg[3] = '-dsafe_mode=0'
308arg[4] = '/usr/local/bin/someport'
309.Ed
310.Pp
311plus any arguments the user specified when executing
312.Pa someport .
313However, this processing of multiple options on the
314.Ql #!
315line is not the way any other operating system parses the
316first line of an interpreted script.
317So after a change which was made for
318.Fx 6.0
319release, that script will result in
320.Pa /usr/local/bin/php
321being started with the arguments of:
322.Bd -literal -offset indent
323arg[0] = '/usr/local/bin/php'
324arg[1] = '-n -q -dsafe_mode=0'
325arg[2] = '/usr/local/bin/someport'
326.Ed
327.Pp
328plus any arguments the user specified.
329This caused a significant change in the behavior of a few scripts.
330In the case of above script, to have it behave the same way under
331.Fx 6.0
332as it did under earlier releases, the first line should be
333changed to:
334.Pp
335.Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
336.Pp
337The
338.Nm
339utility will be started with the entire line as a single
340argument:
341.Pp
342.Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
343.Pp
344and then
345.Fl S
346processing will split that line into separate arguments before
347executing
348.Pa /usr/local/bin/php .
349.\"
350.Sh ENVIRONMENT
351The
352.Nm
353utility uses the
354.Ev PATH
355environment variable to locate the requested
356.Ar utility
357if the name contains no
358.Ql /
359characters, unless the
360.Fl P
361option has been specified.
362.Sh EXIT STATUS
363.Ex -std
364An exit status of 126 indicates that
365.Ar utility
366was found, but could not be executed.
367An exit status of 127 indicates that
368.Ar utility
369could not be found.
370.Sh EXAMPLES
371Since the
372.Nm
373utility is often used as part of the first line of an interpreted script,
374the following examples show a number of ways that the
375.Nm
376utility can be useful in scripts.
377.Pp
378The kernel processing of an interpreted script does not allow a script
379to directly reference some other script as its own interpreter.
380As a way around this, the main difference between
381.Pp
382.Dl #!/usr/local/bin/foo
383and
384.Dl "#!/usr/bin/env /usr/local/bin/foo"
385.Pp
386is that the latter works even if
387.Pa /usr/local/bin/foo
388is itself an interpreted script.
389.Pp
390Probably the most common use of
391.Nm
392is to find the correct interpreter for a script, when the interpreter
393may be in different directories on different systems.
394The following example will find the
395.Ql perl
396interpreter by searching through the directories specified by
397.Ev PATH .
398.Pp
399.Dl "#!/usr/bin/env perl"
400.Pp
401One limitation of that example is that it assumes the user's value
402for
403.Ev PATH
404is set to a value which will find the interpreter you want
405to execute.
406The
407.Fl P
408option can be used to make sure a specific list of directories is
409used in the search for
410.Ar utility .
411Note that the
412.Fl S
413option is also required for this example to work correctly.
414.Pp
415.Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
416.Pp
417The above finds
418.Ql perl
419only if it is in
420.Pa /usr/local/bin
421or
422.Pa /usr/bin .
423That could be combined with the present value of
424.Ev PATH ,
425to provide more flexibility.
426Note that spaces are not required between the
427.Fl S
428and
429.Fl P
430options:
431.Pp
432.Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
433.Sh COMPATIBILITY
434The
435.Nm
436utility accepts the
437.Fl
438option as a synonym for
439.Fl i .
440.Sh SEE ALSO
441.Xr printenv 1 ,
442.Xr sh 1 ,
443.Xr execvp 3 ,
444.Xr environ 7
445.Sh STANDARDS
446The
447.Nm
448utility conforms to
449.St -p1003.1-2001 .
450The
451.Fl P , S , u
452and
453.Fl v
454options are non-standard extensions supported by
455.Fx ,
456but which may not be available on other operating systems.
457.Sh HISTORY
458The
459.Nm
460command appeared in
461.Bx 4.4 .
462The
463.Fl P , S
464and
465.Fl v
466options were added in
467.Fx 6.0 .
468.Sh BUGS
469The
470.Nm
471utility does not handle values of
472.Ar utility
473which have an equals sign
474.Pq Ql =
475in their name, for obvious reasons.
476.Pp
477The
478.Nm
479utility does not take multibyte characters into account when
480processing the
481.Fl S
482option, which may lead to incorrect results in some locales.