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. 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.
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
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
39 .Nd set environment and execute command, or print environment
43 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
47 .Op Ar name Ns = Ns Ar value ...
48 .Op Ar utility Op Ar argument ...
52 utility executes another
54 after modifying the environment as
55 specified on the command line.
57 .Ar name Ns = Ns Ar value
58 option specifies the setting of an environment variable,
62 All such environment variables are set before the
66 The options are as follows:
67 .Bl -tag -width indent
69 End each output line with NUL, not newline.
73 with only those environment variables specified by
74 .Ar name Ns = Ns Ar value
76 The environment inherited
79 is ignored completely.
81 .It Fl L | Fl U Ar user Ns Op / Ns Ar class
82 Add the environment variable definitions from
84 for the specified user and login class to the environment, after
89 options, but before processing any
90 .Ar name Ns = Ns Ar value
94 is used, only the system-wide
95 .Pa /etc/login.conf.db
98 is used, then the specified user's
101 The user may be specified by name or by uid.
104 Search the set of directories as specified by
106 to locate the specified
108 program, instead of using the value of the
110 environment variable.
113 Split apart the given
115 into multiple strings, and process each of the resulting strings
116 as separate arguments to the
121 option recognizes some special character escape sequences and
122 also supports environment-variable substitution, as described
126 If the environment variable
128 is in the environment, then remove it before processing the
130 This is similar to the
141 Print verbose information for each step of processing done by the
144 Additional information will be printed if
146 is specified multiple times.
149 The above options are only recognized when they are specified
151 .Ar name Ns = Ns Ar value
158 prints out the names and values of the variables in the environment.
159 Each name/value pair is separated by a new line unless
161 is specified, in which case name/value pairs are separated by NUL.
166 may not be specified together.
168 .Ss Details of -S (split-string) processing
169 The processing of the
171 option will split the given
173 into separate arguments based on any space or <tab> characters found in the
175 Each of those new arguments will then be treated as if it had been
176 specified as a separate argument on the original
180 Spaces and tabs may be embedded in one of those new arguments by using
185 quotes, or backslashes
187 Single quotes will escape all non-single quote characters, up to
188 the matching single quote.
189 Double quotes will escape all non-double quote characters, up to
190 the matching double quote.
191 It is an error if the end of the
193 is reached before the matching quote character.
197 would create a new argument that starts with the
199 character, then that argument and the remainder of the
204 sequence can be used when you want a new argument to start
207 character, without causing the remainder of the
215 processing will treat certain character combinations as escape
216 sequences which represent some action to take.
217 The character escape sequences are in backslash notation.
218 The characters and their meanings are as follows:
220 .Bl -tag -width indent -offset indent -compact
222 Ignore the remaining characters in the
224 This must not appear inside a double-quoted string.
226 Replace with a <form-feed> character.
228 Replace with a <new-line> character.
230 Replace with a <carriage return> character.
232 Replace with a <tab> character.
234 Replace with a <vertical tab> character.
239 This would be useful when you need a
241 as the first character in one of the arguments created
242 by splitting apart the given
249 If this is found inside of a double-quoted string, then replace it
251 If this is found outside of a quoted string, then treat this as the
252 separator character between new arguments in the original
255 Replace with a <double quote> character.
257 Replace with a <single quote> character.
259 Replace with a backslash character.
262 The sequences for <single-quote> and backslash are the only sequences
263 which are recognized inside of a single-quoted string.
264 The other sequences have no special meaning inside a single-quoted
266 All escape sequences are recognized inside of a double-quoted string.
267 It is an error if a single
269 character is followed by a character other than the ones listed above.
273 also supports substitution of values from environment variables.
274 To do this, the name of the environment variable must be inside of
278 The common shell syntax of
281 All values substituted will be the values of the environment variables
282 as they were when the
284 utility was originally invoked.
285 Those values will not be checked for any of the escape sequences as
288 .Ar name Ns = Ns Ar value
289 will not effect the values used for substitution in
295 processing cannot reference the value of the special parameters
296 which are defined by most shells.
299 cannot recognize special parameters such as:
306 if they appear inside the given
309 .Ss Use in shell-scripts
312 utility is often used as the
314 on the first line of interpreted scripts, as
318 Note that the way the kernel parses the
320 (first line) of an interpreted script has changed as of
324 kernel would split that first line into separate arguments based
325 on any whitespace (space or <tab> characters) found in the line.
326 So, if a script named
327 .Pa /usr/local/bin/someport
330 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
333 .Pa /usr/local/bin/php
334 program would have been started with the arguments of:
335 .Bd -literal -offset indent
336 arg[0] = '/usr/local/bin/php'
339 arg[3] = '-dsafe_mode=0'
340 arg[4] = '/usr/local/bin/someport'
343 plus any arguments the user specified when executing
345 However, this processing of multiple options on the
347 line is not the way any other operating system parses the
348 first line of an interpreted script.
349 So after a change which was made for
351 release, that script will result in
352 .Pa /usr/local/bin/php
353 being started with the arguments of:
354 .Bd -literal -offset indent
355 arg[0] = '/usr/local/bin/php'
356 arg[1] = '-n -q -dsafe_mode=0'
357 arg[2] = '/usr/local/bin/someport'
360 plus any arguments the user specified.
361 This caused a significant change in the behavior of a few scripts.
362 In the case of above script, to have it behave the same way under
364 as it did under earlier releases, the first line should be
367 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
371 utility will be started with the entire line as a single
374 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
378 processing will split that line into separate arguments before
380 .Pa /usr/local/bin/php .
387 environment variable to locate the requested
389 if the name contains no
391 characters, unless the
393 option has been specified.
396 An exit status of 126 indicates that
398 was found, but could not be executed.
399 An exit status of 127 indicates that
405 utility is often used as part of the first line of an interpreted script,
406 the following examples show a number of ways that the
408 utility can be useful in scripts.
410 The kernel processing of an interpreted script does not allow a script
411 to directly reference some other script as its own interpreter.
412 As a way around this, the main difference between
414 .Dl #!/usr/local/bin/foo
416 .Dl "#!/usr/bin/env /usr/local/bin/foo"
418 is that the latter works even if
419 .Pa /usr/local/bin/foo
420 is itself an interpreted script.
422 Probably the most common use of
424 is to find the correct interpreter for a script, when the interpreter
425 may be in different directories on different systems.
426 The following example will find the
428 interpreter by searching through the directories specified by
431 .Dl "#!/usr/bin/env perl"
433 One limitation of that example is that it assumes the user's value
436 is set to a value which will find the interpreter you want
440 option can be used to make sure a specific list of directories is
441 used in the search for
445 option is also required for this example to work correctly.
447 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
455 That could be combined with the present value of
457 to provide more flexibility.
458 Note that spaces are not required between the
464 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
470 option as a synonym for
484 .Fl 0 , L , P , S , U , u
487 options are non-standard extensions supported by
489 but which may not be available on other operating systems.
499 options were added in
505 options were added in
510 utility does not handle values of
512 which have an equals sign
514 in their name, for obvious reasons.
518 utility does not take multibyte characters into account when
521 option, which may lead to incorrect results in some locales.