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
29 .\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
36 .Nd set environment and execute command, or print environment
40 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
42 .Op Ar name Ns = Ns Ar value ...
45 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
49 .Op Ar name Ns = Ns Ar value ...
50 .Ar utility Op Ar argument ...
54 utility executes another
56 after modifying the environment as
57 specified on the command line.
59 .Ar name Ns = Ns Ar value
60 option specifies the setting of an environment variable,
64 All such environment variables are set before the
68 The options are as follows:
69 .Bl -tag -width indent
71 End each output line with NUL, not newline.
75 with only those environment variables specified by
76 .Ar name Ns = Ns Ar value
78 The environment inherited
81 is ignored completely.
83 .It Fl L | Fl U Ar user Ns Op / Ns Ar class
84 Add the environment variable definitions from
86 for the specified user and login class to the environment, after
91 options, but before processing any
92 .Ar name Ns = Ns Ar value
96 is used, only the system-wide
97 .Pa /etc/login.conf.db
100 is used, then the specified user's
103 The user may be specified by name or by uid.
106 is given, then no user lookup will be done, the login class will default to
108 if not explicitly given, and no substitutions will be done on the values.
111 Search the set of directories as specified by
113 to locate the specified
115 program, instead of using the value of the
117 environment variable.
120 Split apart the given
122 into multiple strings, and process each of the resulting strings
123 as separate arguments to the
128 option recognizes some special character escape sequences and
129 also supports environment-variable substitution, as described
133 If the environment variable
135 is in the environment, then remove it before processing the
137 This is similar to the
148 Print verbose information for each step of processing done by the
151 Additional information will be printed if
153 is specified multiple times.
156 The above options are only recognized when they are specified
158 .Ar name Ns = Ns Ar value
165 prints out the names and values of the variables in the environment.
166 Each name/value pair is separated by a new line unless
168 is specified, in which case name/value pairs are separated by NUL.
173 may not be specified together.
175 .Ss Details of -S (split-string) processing
176 The processing of the
178 option will split the given
180 into separate arguments based on any space or <tab> characters found in the
182 Each of those new arguments will then be treated as if it had been
183 specified as a separate argument on the original
187 Spaces and tabs may be embedded in one of those new arguments by using
192 quotes, or backslashes
194 Single quotes will escape all non-single quote characters, up to
195 the matching single quote.
196 Double quotes will escape all non-double quote characters, up to
197 the matching double quote.
198 It is an error if the end of the
200 is reached before the matching quote character.
204 would create a new argument that starts with the
206 character, then that argument and the remainder of the
211 sequence can be used when you want a new argument to start
214 character, without causing the remainder of the
222 processing will treat certain character combinations as escape
223 sequences which represent some action to take.
224 The character escape sequences are in backslash notation.
225 The characters and their meanings are as follows:
227 .Bl -tag -width indent -offset indent -compact
229 Ignore the remaining characters in the
231 This must not appear inside a double-quoted string.
233 Replace with a <form-feed> character.
235 Replace with a <new-line> character.
237 Replace with a <carriage return> character.
239 Replace with a <tab> character.
241 Replace with a <vertical tab> character.
246 This would be useful when you need a
248 as the first character in one of the arguments created
249 by splitting apart the given
256 If this is found inside of a double-quoted string, then replace it
258 If this is found outside of a quoted string, then treat this as the
259 separator character between new arguments in the original
262 Replace with a <double quote> character.
264 Replace with a <single quote> character.
266 Replace with a backslash character.
269 The sequences for <single-quote> and backslash are the only sequences
270 which are recognized inside of a single-quoted string.
271 The other sequences have no special meaning inside a single-quoted
273 All escape sequences are recognized inside of a double-quoted string.
274 It is an error if a single
276 character is followed by a character other than the ones listed above.
280 also supports substitution of values from environment variables.
281 To do this, the name of the environment variable must be inside of
285 The common shell syntax of
288 All values substituted will be the values of the environment variables
289 as they were when the
291 utility was originally invoked.
292 Those values will not be checked for any of the escape sequences as
295 .Ar name Ns = Ns Ar value
296 will not effect the values used for substitution in
302 processing cannot reference the value of the special parameters
303 which are defined by most shells.
306 cannot recognize special parameters such as:
313 if they appear inside the given
316 .Ss Use in shell-scripts
319 utility is often used as the
321 on the first line of interpreted scripts, as
325 Note that the way the kernel parses the
327 (first line) of an interpreted script has changed as of
331 kernel would split that first line into separate arguments based
332 on any whitespace (space or <tab> characters) found in the line.
333 So, if a script named
334 .Pa /usr/local/bin/someport
337 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
340 .Pa /usr/local/bin/php
341 program would have been started with the arguments of:
342 .Bd -literal -offset indent
343 arg[0] = '/usr/local/bin/php'
346 arg[3] = '-dsafe_mode=0'
347 arg[4] = '/usr/local/bin/someport'
350 plus any arguments the user specified when executing
352 However, this processing of multiple options on the
354 line is not the way any other operating system parses the
355 first line of an interpreted script.
356 So after a change which was made for
358 release, that script will result in
359 .Pa /usr/local/bin/php
360 being started with the arguments of:
361 .Bd -literal -offset indent
362 arg[0] = '/usr/local/bin/php'
363 arg[1] = '-n -q -dsafe_mode=0'
364 arg[2] = '/usr/local/bin/someport'
367 plus any arguments the user specified.
368 This caused a significant change in the behavior of a few scripts.
369 In the case of above script, to have it behave the same way under
371 as it did under earlier releases, the first line should be
374 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
378 utility will be started with the entire line as a single
381 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
385 processing will split that line into separate arguments before
387 .Pa /usr/local/bin/php .
394 environment variable to locate the requested
396 if the name contains no
398 characters, unless the
400 option has been specified.
403 An exit status of 126 indicates that
405 was found, but could not be executed.
406 An exit status of 127 indicates that
412 utility is often used as part of the first line of an interpreted script,
413 the following examples show a number of ways that the
415 utility can be useful in scripts.
417 The kernel processing of an interpreted script does not allow a script
418 to directly reference some other script as its own interpreter.
419 As a way around this, the main difference between
421 .Dl #!/usr/local/bin/foo
423 .Dl "#!/usr/bin/env /usr/local/bin/foo"
425 is that the latter works even if
426 .Pa /usr/local/bin/foo
427 is itself an interpreted script.
429 Probably the most common use of
431 is to find the correct interpreter for a script, when the interpreter
432 may be in different directories on different systems.
433 The following example will find the
435 interpreter by searching through the directories specified by
438 .Dl "#!/usr/bin/env perl"
440 One limitation of that example is that it assumes the user's value
443 is set to a value which will find the interpreter you want
447 option can be used to make sure a specific list of directories is
448 used in the search for
452 option is also required for this example to work correctly.
454 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
462 That could be combined with the present value of
464 to provide more flexibility.
465 Note that spaces are not required between the
471 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
477 option as a synonym for
491 .Fl 0 , L , P , S , U , u
494 options are non-standard extensions supported by
496 but which may not be available on other operating systems.
506 options were added in
512 options were added in
517 utility does not handle values of
519 which have an equals sign
521 in their name, for obvious reasons.
525 utility does not take multibyte characters into account when
528 option, which may lead to incorrect results in some locales.