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