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
45 .Op Ar name Ns = Ns Ar value ...
48 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
52 .Op Ar name Ns = Ns Ar value ...
53 .Ar utility Op Ar argument ...
57 utility executes another
59 after modifying the environment as
60 specified on the command line.
62 .Ar name Ns = Ns Ar value
63 option specifies the setting of an environment variable,
67 All such environment variables are set before the
71 The options are as follows:
72 .Bl -tag -width indent
74 End each output line with NUL, not newline.
78 with only those environment variables specified by
79 .Ar name Ns = Ns Ar value
81 The environment inherited
84 is ignored completely.
86 .It Fl L | Fl U Ar user Ns Op / Ns Ar class
87 Add the environment variable definitions from
89 for the specified user and login class to the environment, after
94 options, but before processing any
95 .Ar name Ns = Ns Ar value
99 is used, only the system-wide
100 .Pa /etc/login.conf.db
103 is used, then the specified user's
106 The user may be specified by name or by uid.
109 Search the set of directories as specified by
111 to locate the specified
113 program, instead of using the value of the
115 environment variable.
118 Split apart the given
120 into multiple strings, and process each of the resulting strings
121 as separate arguments to the
126 option recognizes some special character escape sequences and
127 also supports environment-variable substitution, as described
131 If the environment variable
133 is in the environment, then remove it before processing the
135 This is similar to the
146 Print verbose information for each step of processing done by the
149 Additional information will be printed if
151 is specified multiple times.
154 The above options are only recognized when they are specified
156 .Ar name Ns = Ns Ar value
163 prints out the names and values of the variables in the environment.
164 Each name/value pair is separated by a new line unless
166 is specified, in which case name/value pairs are separated by NUL.
171 may not be specified together.
173 .Ss Details of -S (split-string) processing
174 The processing of the
176 option will split the given
178 into separate arguments based on any space or <tab> characters found in the
180 Each of those new arguments will then be treated as if it had been
181 specified as a separate argument on the original
185 Spaces and tabs may be embedded in one of those new arguments by using
190 quotes, or backslashes
192 Single quotes will escape all non-single quote characters, up to
193 the matching single quote.
194 Double quotes will escape all non-double quote characters, up to
195 the matching double quote.
196 It is an error if the end of the
198 is reached before the matching quote character.
202 would create a new argument that starts with the
204 character, then that argument and the remainder of the
209 sequence can be used when you want a new argument to start
212 character, without causing the remainder of the
220 processing will treat certain character combinations as escape
221 sequences which represent some action to take.
222 The character escape sequences are in backslash notation.
223 The characters and their meanings are as follows:
225 .Bl -tag -width indent -offset indent -compact
227 Ignore the remaining characters in the
229 This must not appear inside a double-quoted string.
231 Replace with a <form-feed> character.
233 Replace with a <new-line> character.
235 Replace with a <carriage return> character.
237 Replace with a <tab> character.
239 Replace with a <vertical tab> character.
244 This would be useful when you need a
246 as the first character in one of the arguments created
247 by splitting apart the given
254 If this is found inside of a double-quoted string, then replace it
256 If this is found outside of a quoted string, then treat this as the
257 separator character between new arguments in the original
260 Replace with a <double quote> character.
262 Replace with a <single quote> character.
264 Replace with a backslash character.
267 The sequences for <single-quote> and backslash are the only sequences
268 which are recognized inside of a single-quoted string.
269 The other sequences have no special meaning inside a single-quoted
271 All escape sequences are recognized inside of a double-quoted string.
272 It is an error if a single
274 character is followed by a character other than the ones listed above.
278 also supports substitution of values from environment variables.
279 To do this, the name of the environment variable must be inside of
283 The common shell syntax of
286 All values substituted will be the values of the environment variables
287 as they were when the
289 utility was originally invoked.
290 Those values will not be checked for any of the escape sequences as
293 .Ar name Ns = Ns Ar value
294 will not effect the values used for substitution in
300 processing cannot reference the value of the special parameters
301 which are defined by most shells.
304 cannot recognize special parameters such as:
311 if they appear inside the given
314 .Ss Use in shell-scripts
317 utility is often used as the
319 on the first line of interpreted scripts, as
323 Note that the way the kernel parses the
325 (first line) of an interpreted script has changed as of
329 kernel would split that first line into separate arguments based
330 on any whitespace (space or <tab> characters) found in the line.
331 So, if a script named
332 .Pa /usr/local/bin/someport
335 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
338 .Pa /usr/local/bin/php
339 program would have been started with the arguments of:
340 .Bd -literal -offset indent
341 arg[0] = '/usr/local/bin/php'
344 arg[3] = '-dsafe_mode=0'
345 arg[4] = '/usr/local/bin/someport'
348 plus any arguments the user specified when executing
350 However, this processing of multiple options on the
352 line is not the way any other operating system parses the
353 first line of an interpreted script.
354 So after a change which was made for
356 release, that script will result in
357 .Pa /usr/local/bin/php
358 being started with the arguments of:
359 .Bd -literal -offset indent
360 arg[0] = '/usr/local/bin/php'
361 arg[1] = '-n -q -dsafe_mode=0'
362 arg[2] = '/usr/local/bin/someport'
365 plus any arguments the user specified.
366 This caused a significant change in the behavior of a few scripts.
367 In the case of above script, to have it behave the same way under
369 as it did under earlier releases, the first line should be
372 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
376 utility will be started with the entire line as a single
379 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
383 processing will split that line into separate arguments before
385 .Pa /usr/local/bin/php .
392 environment variable to locate the requested
394 if the name contains no
396 characters, unless the
398 option has been specified.
401 An exit status of 126 indicates that
403 was found, but could not be executed.
404 An exit status of 127 indicates that
410 utility is often used as part of the first line of an interpreted script,
411 the following examples show a number of ways that the
413 utility can be useful in scripts.
415 The kernel processing of an interpreted script does not allow a script
416 to directly reference some other script as its own interpreter.
417 As a way around this, the main difference between
419 .Dl #!/usr/local/bin/foo
421 .Dl "#!/usr/bin/env /usr/local/bin/foo"
423 is that the latter works even if
424 .Pa /usr/local/bin/foo
425 is itself an interpreted script.
427 Probably the most common use of
429 is to find the correct interpreter for a script, when the interpreter
430 may be in different directories on different systems.
431 The following example will find the
433 interpreter by searching through the directories specified by
436 .Dl "#!/usr/bin/env perl"
438 One limitation of that example is that it assumes the user's value
441 is set to a value which will find the interpreter you want
445 option can be used to make sure a specific list of directories is
446 used in the search for
450 option is also required for this example to work correctly.
452 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
460 That could be combined with the present value of
462 to provide more flexibility.
463 Note that spaces are not required between the
469 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
475 option as a synonym for
489 .Fl 0 , L , P , S , U , u
492 options are non-standard extensions supported by
494 but which may not be available on other operating systems.
504 options were added in
510 options were added in
515 utility does not handle values of
517 which have an equals sign
519 in their name, for obvious reasons.
523 utility does not take multibyte characters into account when
526 option, which may lead to incorrect results in some locales.