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