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