usr.bin/env/env.1

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   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
   8 .\" are met:
   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.
  17 .\"
  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
  28 .\" SUCH DAMAGE.
  29 .\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
  30 .\"
  31 .Dd March 3, 2021
  32 .Dt ENV 1
  33 .Os
  34 .Sh NAME
  35 .Nm env
  36 .Nd set environment and execute command, or print environment
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl 0iv
  40 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
  41 .Op Fl u Ar name
  42 .Op Ar name Ns = Ns Ar value ...
  43 .Nm
  44 .Op Fl iv
  45 .Op Fl L Ns | Ns Fl U Ar user Ns Op / Ns Ar class
  46 .Op Fl P Ar altpath
  47 .Op Fl S Ar string
  48 .Op Fl u Ar name
  49 .Op Ar name Ns = Ns Ar value ...
  50 .Ar utility Op Ar argument ...
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility executes another
  55 .Ar utility
  56 after modifying the environment as
  57 specified on the command line.
  58 Each
  59 .Ar name Ns = Ns Ar value
  60 option specifies the setting of an environment variable,
  61 .Ar name ,
  62 with a value of
  63 .Ar value .
  64 All such environment variables are set before the
  65 .Ar utility
  66 is executed.
  67 .Pp
  68 The options are as follows:
  69 .Bl -tag -width indent
  70 .It Fl 0
  71 End each output line with NUL, not newline.
  72 .It Fl i
  73 Execute the
  74 .Ar utility
  75 with only those environment variables specified by
  76 .Ar name Ns = Ns Ar value
  77 options.
  78 The environment inherited
  79 by
  80 .Nm
  81 is ignored completely.
  82 .\"     -L | -U
  83 .It Fl L | Fl U Ar user Ns Op / Ns Ar class
  84 Add the environment variable definitions from
  85 .Xr login.conf 5
  86 for the specified user and login class to the environment, after
  87 processing any
  88 .Fl i
  89 or
  90 .Fl u
  91 options, but before processing any
  92 .Ar name Ns = Ns Ar value
  93 options.
  94 If
  95 .Fl L
  96 is used, only the system-wide
  97 .Pa /etc/login.conf.db
  98 file is read; if
  99 .Fl U
 100 is used, then the specified user's
 101 .Pa ~/.login_conf
 102 is read as well.
 103 The user may be specified by name or by uid.
 104 If a username of
 105 .Sq Li \&-
 106 is given, then no user lookup will be done, the login class will default to
 107 .Sq Li default
 108 if not explicitly given, and no substitutions will be done on the values.
 109 .\"     -P
 110 .It Fl P Ar altpath
 111 Search the set of directories as specified by
 112 .Ar altpath
 113 to locate the specified
 114 .Ar utility
 115 program, instead of using the value of the
 116 .Ev PATH
 117 environment variable.
 118 .\"     -S
 119 .It Fl S Ar string
 120 Split apart the given
 121 .Ar string
 122 into multiple strings, and process each of the resulting strings
 123 as separate arguments to the
 124 .Nm
 125 utility.
 126 The
 127 .Fl S
 128 option recognizes some special character escape sequences and
 129 also supports environment-variable substitution, as described
 130 below.
 131 .\"     -u
 132 .It Fl u Ar name
 133 If the environment variable
 134 .Ar name
 135 is in the environment, then remove it before processing the
 136 remaining options.
 137 This is similar to the
 138 .Ic unset
 139 command in
 140 .Xr sh 1 .
 141 The value for
 142 .Ar name
 143 must not include the
 144 .Ql =
 145 character.
 146 .\"     -v
 147 .It Fl v
 148 Print verbose information for each step of processing done by the
 149 .Nm
 150 utility.
 151 Additional information will be printed if
 152 .Fl v
 153 is specified multiple times.
 154 .El
 155 .Pp
 156 The above options are only recognized when they are specified
 157 before any
 158 .Ar name Ns = Ns Ar value
 159 options.
 160 .Pp
 161 If no
 162 .Ar utility
 163 is specified,
 164 .Nm
 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
 167 .Fl 0
 168 is specified, in which case name/value pairs are separated by NUL.
 169 Both
 170 .Fl 0
 171 and
 172 .Ar utility
 173 may not be specified together.
 174 .\"
 175 .Ss Details of -S (split-string) processing
 176 The processing of the
 177 .Fl S
 178 option will split the given
 179 .Ar string
 180 into separate arguments based on any space or <tab> characters found in the
 181 .Ar string .
 182 Each of those new arguments will then be treated as if it had been
 183 specified as a separate argument on the original
 184 .Nm
 185 command.
 186 .Pp
 187 Spaces and tabs may be embedded in one of those new arguments by using
 188 single
 189 .Pq Dq Li '
 190 or double
 191 .Pq Ql \&"
 192 quotes, or backslashes
 193 .Pq Ql \e .
 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
 199 .Ar string
 200 is reached before the matching quote character.
 201 .Pp
 202 If
 203 .Fl S
 204 would create a new argument that starts with the
 205 .Ql #
 206 character, then that argument and the remainder of the
 207 .Ar string
 208 will be ignored.
 209 The
 210 .Ql \e#
 211 sequence can be used when you want a new argument to start
 212 with a
 213 .Ql #
 214 character, without causing the remainder of the
 215 .Ar string
 216 to be skipped.
 217 .Pp
 218 While processing the
 219 .Ar string
 220 value,
 221 .Fl S
 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:
 226 .Pp
 227 .Bl -tag -width indent -offset indent -compact
 228 .It Cm \ec
 229 Ignore the remaining characters in the
 230 .Ar string .
 231 This must not appear inside a double-quoted string.
 232 .It Cm \ef
 233 Replace with a <form-feed> character.
 234 .It Cm \en
 235 Replace with a <new-line> character.
 236 .It Cm \er
 237 Replace with a <carriage return> character.
 238 .It Cm \et
 239 Replace with a <tab> character.
 240 .It Cm \ev
 241 Replace with a <vertical tab> character.
 242 .It Cm \e#
 243 Replace with a
 244 .Ql #
 245 character.
 246 This would be useful when you need a
 247 .Ql #
 248 as the first character in one of the arguments created
 249 by splitting apart the given
 250 .Ar string .
 251 .It Cm \e$
 252 Replace with a
 253 .Ql $
 254 character.
 255 .It Cm \e_
 256 If this is found inside of a double-quoted string, then replace it
 257 with a single blank.
 258 If this is found outside of a quoted string, then treat this as the
 259 separator character between new arguments in the original
 260 .Ar string .
 261 .It Cm \e"
 262 Replace with a <double quote> character.
 263 .It Cm \e\'
 264 Replace with a <single quote> character.
 265 .It Cm \e\e
 266 Replace with a backslash character.
 267 .El
 268 .Pp
 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
 272 string.
 273 All escape sequences are recognized inside of a double-quoted string.
 274 It is an error if a single
 275 .Ql \e
 276 character is followed by a character other than the ones listed above.
 277 .Pp
 278 The processing of
 279 .Fl S
 280 also supports substitution of values from environment variables.
 281 To do this, the name of the environment variable must be inside of
 282 .Ql ${} ,
 283 such as:
 284 .Li ${SOMEVAR} .
 285 The common shell syntax of
 286 .Li $SOMEVAR
 287 is not supported.
 288 All values substituted will be the values of the environment variables
 289 as they were when the
 290 .Nm
 291 utility was originally invoked.
 292 Those values will not be checked for any of the escape sequences as
 293 described above.
 294 And any settings of
 295 .Ar name Ns = Ns Ar value
 296 will not effect the values used for substitution in
 297 .Fl S
 298 processing.
 299 .Pp
 300 Also,
 301 .Fl S
 302 processing cannot reference the value of the special parameters
 303 which are defined by most shells.
 304 For instance,
 305 .Fl S
 306 cannot recognize special parameters such as:
 307 .Ql $* ,
 308 .Ql $@ ,
 309 .Ql $# ,
 310 .Ql $?
 311 or
 312 .Ql $$
 313 if they appear inside the given
 314 .Ar string .
 315 .\"
 316 .Ss Use in shell-scripts
 317 The
 318 .Nm
 319 utility is often used as the
 320 .Ar interpreter
 321 on the first line of interpreted scripts, as
 322 described in
 323 .Xr execve 2 .
 324 .Pp
 325 Note that the way the kernel parses the
 326 .Ql #!
 327 (first line) of an interpreted script has changed as of
 328 .Fx 6.0 .
 329 Prior to that, the
 330 .Fx
 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
 335 had a first line of:
 336 .Pp
 337 .Dl "#!/usr/local/bin/php -n -q -dsafe_mode=0"
 338 .Pp
 339 then the
 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'
 344 arg[1] = '-n'
 345 arg[2] = '-q'
 346 arg[3] = '-dsafe_mode=0'
 347 arg[4] = '/usr/local/bin/someport'
 348 .Ed
 349 .Pp
 350 plus any arguments the user specified when executing
 351 .Pa someport .
 352 However, this processing of multiple options on the
 353 .Ql #!
 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
 357 .Fx 6.0
 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'
 365 .Ed
 366 .Pp
 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
 370 .Fx 6.0
 371 as it did under earlier releases, the first line should be
 372 changed to:
 373 .Pp
 374 .Dl "#!/usr/bin/env -S /usr/local/bin/php -n -q -dsafe_mode=0"
 375 .Pp
 376 The
 377 .Nm
 378 utility will be started with the entire line as a single
 379 argument:
 380 .Pp
 381 .Dl "arg[1] = '-S /usr/local/bin/php -n -q -dsafe_mode=0'"
 382 .Pp
 383 and then
 384 .Fl S
 385 processing will split that line into separate arguments before
 386 executing
 387 .Pa /usr/local/bin/php .
 388 .\"
 389 .Sh ENVIRONMENT
 390 The
 391 .Nm
 392 utility uses the
 393 .Ev PATH
 394 environment variable to locate the requested
 395 .Ar utility
 396 if the name contains no
 397 .Ql /
 398 characters, unless the
 399 .Fl P
 400 option has been specified.
 401 .Sh EXIT STATUS
 402 .Ex -std
 403 An exit status of 126 indicates that
 404 .Ar utility
 405 was found, but could not be executed.
 406 An exit status of 127 indicates that
 407 .Ar utility
 408 could not be found.
 409 .Sh EXAMPLES
 410 Since the
 411 .Nm
 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
 414 .Nm
 415 utility can be useful in scripts.
 416 .Pp
 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
 420 .Pp
 421 .Dl #!/usr/local/bin/foo
 422 and
 423 .Dl "#!/usr/bin/env /usr/local/bin/foo"
 424 .Pp
 425 is that the latter works even if
 426 .Pa /usr/local/bin/foo
 427 is itself an interpreted script.
 428 .Pp
 429 Probably the most common use of
 430 .Nm
 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
 434 .Ql perl
 435 interpreter by searching through the directories specified by
 436 .Ev PATH .
 437 .Pp
 438 .Dl "#!/usr/bin/env perl"
 439 .Pp
 440 One limitation of that example is that it assumes the user's value
 441 for
 442 .Ev PATH
 443 is set to a value which will find the interpreter you want
 444 to execute.
 445 The
 446 .Fl P
 447 option can be used to make sure a specific list of directories is
 448 used in the search for
 449 .Ar utility .
 450 Note that the
 451 .Fl S
 452 option is also required for this example to work correctly.
 453 .Pp
 454 .Dl "#!/usr/bin/env -S -P/usr/local/bin:/usr/bin perl"
 455 .Pp
 456 The above finds
 457 .Ql perl
 458 only if it is in
 459 .Pa /usr/local/bin
 460 or
 461 .Pa /usr/bin .
 462 That could be combined with the present value of
 463 .Ev PATH ,
 464 to provide more flexibility.
 465 Note that spaces are not required between the
 466 .Fl S
 467 and
 468 .Fl P
 469 options:
 470 .Pp
 471 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
 472 .Sh COMPATIBILITY
 473 The
 474 .Nm
 475 utility accepts the
 476 .Fl
 477 option as a synonym for
 478 .Fl i .
 479 .Sh SEE ALSO
 480 .Xr printenv 1 ,
 481 .Xr sh 1 ,
 482 .Xr execvp 3 ,
 483 .Xr login.conf 5 ,
 484 .Xr environ 7
 485 .Sh STANDARDS
 486 The
 487 .Nm
 488 utility conforms to
 489 .St -p1003.1-2001 .
 490 The
 491 .Fl 0 , L , P , S , U , u
 492 and
 493 .Fl v
 494 options are non-standard extensions supported by
 495 .Fx ,
 496 but which may not be available on other operating systems.
 497 .Sh HISTORY
 498 The
 499 .Nm
 500 command appeared in
 501 .Bx 4.4 .
 502 The
 503 .Fl P , S
 504 and
 505 .Fl v
 506 options were added in
 507 .Fx 6.0 .
 508 The
 509 .Fl 0 , L
 510 and
 511 .Fl U
 512 options were added in
 513 .Fx 13.0 .
 514 .Sh BUGS
 515 The
 516 .Nm
 517 utility does not handle values of
 518 .Ar utility
 519 which have an equals sign
 520 .Pq Ql =
 521 in their name, for obvious reasons.
 522 .Pp
 523 The
 524 .Nm
 525 utility does not take multibyte characters into account when
 526 processing the
 527 .Fl S
 528 option, which may lead to incorrect results in some locales.