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
38 .Nd set environment and execute command, or print environment
42 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
44 .Op Ar name Ns = Ns Ar value ...
47 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
51 .Op Ar name Ns = Ns Ar value ...
52 .Ar utility Op Ar argument ...
56 utility executes another
58 after modifying the environment as
59 specified on the command line.
61 .Ar name Ns = Ns Ar value
62 option specifies the setting of an environment variable,
66 All such environment variables are set before the
70 The options are as follows:
71 .Bl -tag -width indent
73 End each output line with NUL, not newline.
77 with only those environment variables specified by
78 .Ar name Ns = Ns Ar value
80 The environment inherited
83 is ignored completely.
85 .It Fl L | Fl U Ar user Ns Op / Ns Ar class
86 Add the environment variable definitions from
88 for the specified user and login class to the environment, after
93 options, but before processing any
94 .Ar name Ns = Ns Ar value
98 is used, only the system-wide
99 .Pa /etc/login.conf.db
102 is used, then the specified user's
105 The user may be specified by name or by uid.
108 is given, then no user lookup will be done, the login class will default to
110 if not explicitly given, and no substitutions will be done on the values.
113 Search the set of directories as specified by
115 to locate the specified
117 program, instead of using the value of the
119 environment variable.
122 Split apart the given
124 into multiple strings, and process each of the resulting strings
125 as separate arguments to the
130 option recognizes some special character escape sequences and
131 also supports environment-variable substitution, as described
135 If the environment variable
137 is in the environment, then remove it before processing the
139 This is similar to the
150 Print verbose information for each step of processing done by the
153 Additional information will be printed if
155 is specified multiple times.
158 The above options are only recognized when they are specified
160 .Ar name Ns = Ns Ar value
167 prints out the names and values of the variables in the environment.
168 Each name/value pair is separated by a new line unless
170 is specified, in which case name/value pairs are separated by NUL.
175 may not be specified together.
177 .Ss Details of -S (split-string) processing
178 The processing of the
180 option will split the given
182 into separate arguments based on any space or <tab> characters found in the
184 Each of those new arguments will then be treated as if it had been
185 specified as a separate argument on the original
189 Spaces and tabs may be embedded in one of those new arguments by using
194 quotes, or backslashes
196 Single quotes will escape all non-single quote characters, up to
197 the matching single quote.
198 Double quotes will escape all non-double quote characters, up to
199 the matching double quote.
200 It is an error if the end of the
202 is reached before the matching quote character.
206 would create a new argument that starts with the
208 character, then that argument and the remainder of the
213 sequence can be used when you want a new argument to start
216 character, without causing the remainder of the
224 processing will treat certain character combinations as escape
225 sequences which represent some action to take.
226 The character escape sequences are in backslash notation.
227 The characters and their meanings are as follows:
229 .Bl -tag -width indent -offset indent -compact
231 Ignore the remaining characters in the
233 This must not appear inside a double-quoted string.
235 Replace with a <form-feed> character.
237 Replace with a <new-line> character.
239 Replace with a <carriage return> character.
241 Replace with a <tab> character.
243 Replace with a <vertical tab> character.
248 This would be useful when you need a
250 as the first character in one of the arguments created
251 by splitting apart the given
258 If this is found inside of a double-quoted string, then replace it
260 If this is found outside of a quoted string, then treat this as the
261 separator character between new arguments in the original
264 Replace with a <double quote> character.
266 Replace with a <single quote> character.
268 Replace with a backslash character.
271 The sequences for <single-quote> and backslash are the only sequences
272 which are recognized inside of a single-quoted string.
273 The other sequences have no special meaning inside a single-quoted
275 All escape sequences are recognized inside of a double-quoted string.
276 It is an error if a single
278 character is followed by a character other than the ones listed above.
282 also supports substitution of values from environment variables.
283 To do this, the name of the environment variable must be inside of
287 The common shell syntax of
290 All values substituted will be the values of the environment variables
291 as they were when the
293 utility was originally invoked.
294 Those values will not be checked for any of the escape sequences as
297 .Ar name Ns = Ns Ar value
298 will not effect the values used for substitution in
304 processing cannot reference the value of the special parameters
305 which are defined by most shells.
308 cannot recognize special parameters such as:
315 if they appear inside the given
318 .Ss Use in shell-scripts
321 utility is often used as the
323 on the first line of interpreted scripts, as
327 Note that the way the kernel parses the
329 (first line) of an interpreted script has changed as of
333 kernel would split that first line into separate arguments based
334 on any whitespace (space or <tab> characters) found in the line.
335 So, if a script named
336 .Pa /usr/local/bin/someport
339 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
342 .Pa /usr/local/bin/php
343 program would have been started with the arguments of:
344 .Bd -literal -offset indent
345 arg[0] = '/usr/local/bin/php'
348 arg[3] = '-dsafe_mode=0'
349 arg[4] = '/usr/local/bin/someport'
352 plus any arguments the user specified when executing
354 However, this processing of multiple options on the
356 line is not the way any other operating system parses the
357 first line of an interpreted script.
358 So after a change which was made for
360 release, that script will result in
361 .Pa /usr/local/bin/php
362 being started with the arguments of:
363 .Bd -literal -offset indent
364 arg[0] = '/usr/local/bin/php'
365 arg[1] = '-n -q -dsafe_mode=0'
366 arg[2] = '/usr/local/bin/someport'
369 plus any arguments the user specified.
370 This caused a significant change in the behavior of a few scripts.
371 In the case of above script, to have it behave the same way under
373 as it did under earlier releases, the first line should be
376 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
380 utility will be started with the entire line as a single
383 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
387 processing will split that line into separate arguments before
389 .Pa /usr/local/bin/php .
396 environment variable to locate the requested
398 if the name contains no
400 characters, unless the
402 option has been specified.
405 An exit status of 126 indicates that
407 was found, but could not be executed.
408 An exit status of 127 indicates that
414 utility is often used as part of the first line of an interpreted script,
415 the following examples show a number of ways that the
417 utility can be useful in scripts.
419 The kernel processing of an interpreted script does not allow a script
420 to directly reference some other script as its own interpreter.
421 As a way around this, the main difference between
423 .Dl #!/usr/local/bin/foo
425 .Dl "#!/usr/bin/env /usr/local/bin/foo"
427 is that the latter works even if
428 .Pa /usr/local/bin/foo
429 is itself an interpreted script.
431 Probably the most common use of
433 is to find the correct interpreter for a script, when the interpreter
434 may be in different directories on different systems.
435 The following example will find the
437 interpreter by searching through the directories specified by
440 .Dl "#!/usr/bin/env perl"
442 One limitation of that example is that it assumes the user's value
445 is set to a value which will find the interpreter you want
449 option can be used to make sure a specific list of directories is
450 used in the search for
454 option is also required for this example to work correctly.
456 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
464 That could be combined with the present value of
466 to provide more flexibility.
467 Note that spaces are not required between the
473 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
479 option as a synonym for
493 .Fl 0 , L , P , S , U , u
496 options are non-standard extensions supported by
498 but which may not be available on other operating systems.
508 options were added in
514 options were added in
519 utility does not handle values of
521 which have an equals sign
523 in their name, for obvious reasons.
527 utility does not take multibyte characters into account when
530 option, which may lead to incorrect results in some locales.