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