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 is given, then no user lookup will be done, the login class will default to
111 if not explicitly given, and no substitutions will be done on the values.
114 Search the set of directories as specified by
116 to locate the specified
118 program, instead of using the value of the
120 environment variable.
123 Split apart the given
125 into multiple strings, and process each of the resulting strings
126 as separate arguments to the
131 option recognizes some special character escape sequences and
132 also supports environment-variable substitution, as described
136 If the environment variable
138 is in the environment, then remove it before processing the
140 This is similar to the
151 Print verbose information for each step of processing done by the
154 Additional information will be printed if
156 is specified multiple times.
159 The above options are only recognized when they are specified
161 .Ar name Ns = Ns Ar value
168 prints out the names and values of the variables in the environment.
169 Each name/value pair is separated by a new line unless
171 is specified, in which case name/value pairs are separated by NUL.
176 may not be specified together.
178 .Ss Details of -S (split-string) processing
179 The processing of the
181 option will split the given
183 into separate arguments based on any space or <tab> characters found in the
185 Each of those new arguments will then be treated as if it had been
186 specified as a separate argument on the original
190 Spaces and tabs may be embedded in one of those new arguments by using
195 quotes, or backslashes
197 Single quotes will escape all non-single quote characters, up to
198 the matching single quote.
199 Double quotes will escape all non-double quote characters, up to
200 the matching double quote.
201 It is an error if the end of the
203 is reached before the matching quote character.
207 would create a new argument that starts with the
209 character, then that argument and the remainder of the
214 sequence can be used when you want a new argument to start
217 character, without causing the remainder of the
225 processing will treat certain character combinations as escape
226 sequences which represent some action to take.
227 The character escape sequences are in backslash notation.
228 The characters and their meanings are as follows:
230 .Bl -tag -width indent -offset indent -compact
232 Ignore the remaining characters in the
234 This must not appear inside a double-quoted string.
236 Replace with a <form-feed> character.
238 Replace with a <new-line> character.
240 Replace with a <carriage return> character.
242 Replace with a <tab> character.
244 Replace with a <vertical tab> character.
249 This would be useful when you need a
251 as the first character in one of the arguments created
252 by splitting apart the given
259 If this is found inside of a double-quoted string, then replace it
261 If this is found outside of a quoted string, then treat this as the
262 separator character between new arguments in the original
265 Replace with a <double quote> character.
267 Replace with a <single quote> character.
269 Replace with a backslash character.
272 The sequences for <single-quote> and backslash are the only sequences
273 which are recognized inside of a single-quoted string.
274 The other sequences have no special meaning inside a single-quoted
276 All escape sequences are recognized inside of a double-quoted string.
277 It is an error if a single
279 character is followed by a character other than the ones listed above.
283 also supports substitution of values from environment variables.
284 To do this, the name of the environment variable must be inside of
288 The common shell syntax of
291 All values substituted will be the values of the environment variables
292 as they were when the
294 utility was originally invoked.
295 Those values will not be checked for any of the escape sequences as
298 .Ar name Ns = Ns Ar value
299 will not effect the values used for substitution in
305 processing cannot reference the value of the special parameters
306 which are defined by most shells.
309 cannot recognize special parameters such as:
316 if they appear inside the given
319 .Ss Use in shell-scripts
322 utility is often used as the
324 on the first line of interpreted scripts, as
328 Note that the way the kernel parses the
330 (first line) of an interpreted script has changed as of
334 kernel would split that first line into separate arguments based
335 on any whitespace (space or <tab> characters) found in the line.
336 So, if a script named
337 .Pa /usr/local/bin/someport
340 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
343 .Pa /usr/local/bin/php
344 program would have been started with the arguments of:
345 .Bd -literal -offset indent
346 arg[0] = '/usr/local/bin/php'
349 arg[3] = '-dsafe_mode=0'
350 arg[4] = '/usr/local/bin/someport'
353 plus any arguments the user specified when executing
355 However, this processing of multiple options on the
357 line is not the way any other operating system parses the
358 first line of an interpreted script.
359 So after a change which was made for
361 release, that script will result in
362 .Pa /usr/local/bin/php
363 being started with the arguments of:
364 .Bd -literal -offset indent
365 arg[0] = '/usr/local/bin/php'
366 arg[1] = '-n -q -dsafe_mode=0'
367 arg[2] = '/usr/local/bin/someport'
370 plus any arguments the user specified.
371 This caused a significant change in the behavior of a few scripts.
372 In the case of above script, to have it behave the same way under
374 as it did under earlier releases, the first line should be
377 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
381 utility will be started with the entire line as a single
384 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
388 processing will split that line into separate arguments before
390 .Pa /usr/local/bin/php .
397 environment variable to locate the requested
399 if the name contains no
401 characters, unless the
403 option has been specified.
406 An exit status of 126 indicates that
408 was found, but could not be executed.
409 An exit status of 127 indicates that
415 utility is often used as part of the first line of an interpreted script,
416 the following examples show a number of ways that the
418 utility can be useful in scripts.
420 The kernel processing of an interpreted script does not allow a script
421 to directly reference some other script as its own interpreter.
422 As a way around this, the main difference between
424 .Dl #!/usr/local/bin/foo
426 .Dl "#!/usr/bin/env /usr/local/bin/foo"
428 is that the latter works even if
429 .Pa /usr/local/bin/foo
430 is itself an interpreted script.
432 Probably the most common use of
434 is to find the correct interpreter for a script, when the interpreter
435 may be in different directories on different systems.
436 The following example will find the
438 interpreter by searching through the directories specified by
441 .Dl "#!/usr/bin/env perl"
443 One limitation of that example is that it assumes the user's value
446 is set to a value which will find the interpreter you want
450 option can be used to make sure a specific list of directories is
451 used in the search for
455 option is also required for this example to work correctly.
457 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
465 That could be combined with the present value of
467 to provide more flexibility.
468 Note that spaces are not required between the
474 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
480 option as a synonym for
494 .Fl 0 , L , P , S , U , u
497 options are non-standard extensions supported by
499 but which may not be available on other operating systems.
509 options were added in
515 options were added in
520 utility does not handle values of
522 which have an equals sign
524 in their name, for obvious reasons.
528 utility does not take multibyte characters into account when
531 option, which may lead to incorrect results in some locales.