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