/usr.bin/env/env.1

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 482 lines · 482 code · 0 blank · 0 comment · 0 complexity · 6c9bab9d8f34c972199ea6e7dc320ed1 MD5 · raw file

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