1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
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
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 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" From @(#)printenv.1 8.1 (Berkeley) 6/6/93
35 .\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
43 .Nd set environment and execute command, or print environment
50 .Op Ar name Ns = Ns Ar value ...
51 .Op Ar utility Op Ar argument ...
55 utility executes another
57 after modifying the environment as
58 specified on the command line.
60 .Ar name Ns = Ns Ar value
61 option specifies the setting of an environment variable,
65 All such environment variables are set before the
69 The options are as follows:
70 .Bl -tag -width indent
74 with only those environment variables specified by
75 .Ar name Ns = Ns Ar value
77 The environment inherited
80 is ignored completely.
83 Search the set of directories as specified by
85 to locate the specified
87 program, instead of using the value of the
94 into multiple strings, and process each of the resulting strings
95 as separate arguments to the
100 option recognizes some special character escape sequences and
101 also supports environment-variable substitution, as described
105 If the environment variable
107 is in the environment, then remove it before processing the
109 This is similar to the
120 Print verbose information for each step of processing done by the
123 Additional information will be printed if
125 is specified multiple times.
128 The above options are only recognized when they are specified
130 .Ar name Ns = Ns Ar value
137 prints out the names and values
138 of the variables in the environment, with one name/value pair per line.
140 .Ss Details of Fl S Ss (split-string) processing
141 The processing of the
143 option will split the given
145 into separate arguments based on any space or <tab> characters found in the
147 Each of those new arguments will then be treated as if it had been
148 specified as a separate argument on the original
152 Spaces and tabs may be embedded in one of those new arguments by using
157 quotes, or backslashes
159 Single quotes will escape all non-single quote characters, up to
160 the matching single quote.
161 Double quotes will escape all non-double quote characters, up to
162 the matching double quote.
163 It is an error if the end of the
165 is reached before the matching quote character.
169 would create a new argument that starts with the
171 character, then that argument and the remainder of the
176 sequence can be used when you want a new argument to start
179 character, without causing the remainder of the
187 processing will treat certain character combinations as escape
188 sequences which represent some action to take.
189 The character escape sequences are in backslash notation.
190 The characters and their meanings are as follows:
192 .Bl -tag -width indent -offset indent -compact
194 Ignore the remaining characters in the
196 This must not appear inside a double-quoted string.
198 Replace with a <form-feed> character.
200 Replace with a <new-line> character.
202 Replace with a <carriage return> character.
204 Replace with a <tab> character.
206 Replace with a <vertical tab> character.
211 This would be useful when you need a
213 as the first character in one of the arguments created
214 by splitting apart the given
221 If this is found inside of a double-quoted string, then replace it
223 If this is found outside of a quoted string, then treat this as the
224 separator character between new arguments in the original
227 Replace with a <double quote> character.
229 Replace with a <single quote> character.
231 Replace with a backslash character.
234 The sequences for <single-quote> and backslash are the only sequences
235 which are recognized inside of a single-quoted string.
236 The other sequences have no special meaning inside a single-quoted
238 All escape sequences are recognized inside of a double-quoted string.
239 It is an error if a single
241 character is followed by a character other than the ones listed above.
245 also supports substitution of values from environment variables.
246 To do this, the name of the environment variable must be inside of
250 The common shell syntax of
253 All values substituted will be the values of the environment variables
254 as they were when the
256 utility was originally invoked.
257 Those values will not be checked for any of the escape sequences as
260 .Ar name Ns = Ns Ar value
261 will not effect the values used for substitution in
267 processing can not reference the value of the special parameters
268 which are defined by most shells.
271 can not recognize special parameters such as:
278 if they appear inside the given
281 .Ss Use in shell-scripts
284 utility is often used as the
286 on the first line of interpreted scripts, as
290 Note that the way the kernel parses the
292 (first line) of an interpreted script has changed as of
296 kernel would split that first line into separate arguments based
297 on any whitespace (space or <tab> characters) found in the line.
298 So, if a script named
299 .Pa /usr/local/bin/someport
302 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
305 .Pa /usr/local/bin/php
306 program would have been started with the arguments of:
307 .Bd -literal -offset indent
308 arg[0] = '/usr/local/bin/php'
311 arg[3] = '-dsafe_mode=0'
312 arg[4] = '/usr/local/bin/someport'
315 plus any arguments the user specified when executing
317 However, this processing of multiple options on the
319 line is not the way any other operating system parses the
320 first line of an interpreted script.
321 So after a change which was made for
323 release, that script will result in
324 .Pa /usr/local/bin/php
325 being started with the arguments of:
326 .Bd -literal -offset indent
327 arg[0] = '/usr/local/bin/php'
328 arg[1] = '-n -q -dsafe_mode=0'
329 arg[2] = '/usr/local/bin/someport'
332 plus any arguments the user specified.
333 This caused a significant change in the behavior of a few scripts.
334 In the case of above script, to have it behave the same way under
336 as it did under earlier releases, the first line should be
339 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
343 utility will be started with the entire line as a single
346 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
350 processing will split that line into separate arguments before
352 .Pa /usr/local/bin/php .
359 environment variable to locate the requested
361 if the name contains no
363 characters, unless the
365 option has been specified.
368 An exit status of 126 indicates that
370 was found, but could not be executed.
371 An exit status of 127 indicates that
377 utility is often used as part of the first line of an interpreted script,
378 the following examples show a number of ways that the
380 utility can be useful in scripts.
382 The kernel processing of an interpreted script does not allow a script
383 to directly reference some other script as its own interpreter.
384 As a way around this, the main difference between
386 .Dl #!/usr/local/bin/foo
388 .Dl "#!/usr/bin/env /usr/local/bin/foo"
390 is that the latter works even if
391 .Pa /usr/local/bin/foo
392 is itself an interpreted script.
394 Probably the most common use of
396 is to find the correct interpreter for a script, when the interpreter
397 may be in different directories on different systems.
398 The following example will find the
400 interpreter by searching through the directories specified by
403 .Dl "#!/usr/bin/env perl"
405 One limitation of that example is that it assumes the user's value
408 is set to a value which will find the interpreter you want
412 option can be used to make sure a specific list of directories is
413 used in the search for
417 option is also required for this example to work correctly.
419 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
427 That could be combined with the present value of
429 to provide more flexibility.
430 Note that spaces are not required between the
436 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
442 option as a synonym for
458 options are non-standard extensions supported by
460 but which may not be available on other operating systems.
470 options were added in
475 utility does not handle values of
477 which have an equals sign
479 in their name, for obvious reasons.
483 utility does not take multibyte characters into account when
486 option, which may lead to incorrect results in some locales.