logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

env.1p (9232B)


  1. '\" et
  2. .TH ENV "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. env
  12. \(em set the environment for command invocation
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. env \fB[\fR-i\fB] [\fIname\fR=\fIvalue\fB]\fR... \fB[\fIutility\fB [\fIargument\fR...\fB]]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR env
  21. utility shall obtain the current environment, modify it according to
  22. its arguments, then invoke the utility named by the
  23. .IR utility
  24. operand with the modified environment.
  25. .P
  26. Optional arguments shall be passed to
  27. .IR utility .
  28. .P
  29. If no
  30. .IR utility
  31. operand is specified, the resulting environment shall be written to the
  32. standard output, with one
  33. .IR name =\c
  34. .IR value
  35. pair per line.
  36. .P
  37. If the first argument is
  38. .BR '\-' ,
  39. the results are unspecified.
  40. .SH OPTIONS
  41. The
  42. .IR env
  43. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  44. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  45. except for the unspecified usage of
  46. .BR '\-' .
  47. .P
  48. The following options shall be supported:
  49. .IP "\fB\-i\fP" 10
  50. Invoke
  51. .IR utility
  52. with exactly the environment specified by the arguments; the inherited
  53. environment shall be ignored completely.
  54. .SH OPERANDS
  55. The following operands shall be supported:
  56. .IP "\fIname\fR=\fIvalue\fR" 10
  57. Arguments of the form
  58. .IR name =\c
  59. .IR value
  60. shall modify the execution environment, and shall be placed into the
  61. inherited environment before the
  62. .IR utility
  63. is invoked.
  64. .IP "\fIutility\fR" 10
  65. The name of the utility to be invoked. If the
  66. .IR utility
  67. operand names any of the special built-in utilities in
  68. .IR "Section 2.14" ", " "Special Built-In Utilities",
  69. the results are undefined.
  70. .IP "\fIargument\fR" 10
  71. A string to pass as an argument for the invoked utility.
  72. .SH STDIN
  73. Not used.
  74. .SH "INPUT FILES"
  75. None.
  76. .SH "ENVIRONMENT VARIABLES"
  77. The following environment variables shall affect the execution of
  78. .IR env :
  79. .IP "\fILANG\fP" 10
  80. Provide a default value for the internationalization variables that are
  81. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  82. .IR "Section 8.2" ", " "Internationalization Variables"
  83. for the precedence of internationalization variables used to determine
  84. the values of locale categories.)
  85. .IP "\fILC_ALL\fP" 10
  86. If set to a non-empty string value, override the values of all the
  87. other internationalization variables.
  88. .IP "\fILC_CTYPE\fP" 10
  89. Determine the locale for the interpretation of sequences of bytes of
  90. text data as characters (for example, single-byte as opposed to
  91. multi-byte characters in arguments).
  92. .IP "\fILC_MESSAGES\fP" 10
  93. .br
  94. Determine the locale that should be used to affect the format and
  95. contents of diagnostic messages written to standard error.
  96. .IP "\fINLSPATH\fP" 10
  97. Determine the location of message catalogs for the processing of
  98. .IR LC_MESSAGES .
  99. .IP "\fIPATH\fP" 10
  100. Determine the location of the
  101. .IR utility ,
  102. as described in the Base Definitions volume of POSIX.1\(hy2017,
  103. .IR "Chapter 8" ", " "Environment Variables".
  104. If
  105. .IR PATH
  106. is specified as a
  107. .IR name =\c
  108. .IR value
  109. operand to
  110. .IR env ,
  111. the
  112. .IR value
  113. given shall be used in the search for
  114. .IR utility .
  115. .SH "ASYNCHRONOUS EVENTS"
  116. Default.
  117. .SH STDOUT
  118. If no
  119. .IR utility
  120. operand is specified, each
  121. .IR name =\c
  122. .IR value
  123. pair in the resulting environment shall be written in the form:
  124. .sp
  125. .RS 4
  126. .nf
  127. "%s=%s\en", <\fIname\fR>, <\fIvalue\fR>
  128. .fi
  129. .P
  130. .RE
  131. .P
  132. If the
  133. .IR utility
  134. operand is specified, the
  135. .IR env
  136. utility shall not write to standard output.
  137. .SH STDERR
  138. The standard error shall be used only for diagnostic messages.
  139. .SH "OUTPUT FILES"
  140. None.
  141. .SH "EXTENDED DESCRIPTION"
  142. None.
  143. .SH "EXIT STATUS"
  144. If
  145. .IR utility
  146. is invoked, the exit status of
  147. .IR env
  148. shall be the exit status of
  149. .IR utility ;
  150. otherwise, the
  151. .IR env
  152. utility shall exit with one of the following values:
  153. .IP "\0\0\0\00" 8
  154. The
  155. .IR env
  156. utility completed successfully.
  157. .IP "1\-125" 8
  158. An error occurred in the
  159. .IR env
  160. utility.
  161. .IP "\0\0126" 8
  162. The utility specified by
  163. .IR utility
  164. was found but could not be invoked.
  165. .IP "\0\0127" 8
  166. The utility specified by
  167. .IR utility
  168. could not be found.
  169. .SH "CONSEQUENCES OF ERRORS"
  170. Default.
  171. .LP
  172. .IR "The following sections are informative."
  173. .SH "APPLICATION USAGE"
  174. The
  175. .IR command ,
  176. .IR env ,
  177. .IR nice ,
  178. .IR nohup ,
  179. .IR time ,
  180. and
  181. .IR xargs
  182. utilities have been specified to use exit code 127 if an error occurs
  183. so that applications can distinguish ``failure to find a utility'' from
  184. ``invoked utility exited with an error indication''. The value 127 was
  185. chosen because it is not commonly used for other meanings; most
  186. utilities use small values for ``normal error conditions'' and the
  187. values above 128 can be confused with termination due to receipt of a
  188. signal. The value 126 was chosen in a similar manner to indicate that
  189. the utility could be found, but not invoked. Some scripts produce
  190. meaningful error messages differentiating the 126 and 127 cases. The
  191. distinction between exit codes 126 and 127 is based on KornShell
  192. practice that uses 127 when all attempts to
  193. .IR exec
  194. the utility fail with
  195. .BR [ENOENT] ,
  196. and uses 126 when any attempt to
  197. .IR exec
  198. the utility fails for any other reason.
  199. .P
  200. Historical implementations of the
  201. .IR env
  202. utility use the
  203. \fIexecvp\fR()
  204. or
  205. \fIexeclp\fR()
  206. functions defined in the System Interfaces volume of POSIX.1\(hy2017 to invoke the specified utility; this
  207. provides better performance and keeps users from having to escape
  208. characters with special meaning to the shell. Therefore, shell
  209. functions, special built-ins, and built-ins that are only provided by
  210. the shell are not found.
  211. .SH EXAMPLES
  212. The following command:
  213. .sp
  214. .RS 4
  215. .nf
  216. env -i PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile
  217. .fi
  218. .P
  219. .RE
  220. .P
  221. invokes the command
  222. .IR mygrep
  223. with a new
  224. .IR PATH
  225. value as the only entry in its environment other than any variables
  226. required by the implementation for conformance. In this case,
  227. .IR PATH
  228. is used to locate
  229. .IR mygrep ,
  230. which is expected to reside in
  231. .BR /mybin .
  232. .SH RATIONALE
  233. As with all other utilities that invoke other utilities, this volume of POSIX.1\(hy2017 only
  234. specifies what
  235. .IR env
  236. does with standard input, standard output, standard error, input files,
  237. and output files. If a utility is executed, it is not constrained by
  238. the specification of input and output by
  239. .IR env .
  240. .P
  241. The
  242. .BR \-i
  243. option was added to allow the functionality of the removed
  244. .BR \-
  245. option in a manner compatible with the Utility Syntax Guidelines. It
  246. is possible to create a non-conforming environment using the
  247. .BR \-i
  248. option, as it may remove environment variables required by the
  249. implementation for conformance. The following will preserve these
  250. environment variables as well as preserve the
  251. .IR PATH
  252. for conforming utilities:
  253. .sp
  254. .RS 4
  255. .nf
  256. IFS=\(aq
  257. \&\(aq
  258. # The preceding value should be <space><tab><newline>.
  259. # Set IFS to its default value.
  260. .P
  261. set -f
  262. # disable pathname expansion
  263. .P
  264. \eunalias -a
  265. # Unset all possible aliases.
  266. # Note that unalias is escaped to prevent an alias
  267. # being used for unalias.
  268. # This step is not strictly necessary, since aliases are not inherited,
  269. # and the ENV environment variable is only used by interactive shells,
  270. # the only way any aliases can exist in a script is if it defines them
  271. # itself.
  272. .P
  273. unset -f env getconf
  274. # Ensure env and getconf are not user functions.
  275. .P
  276. env -i $(getconf V7_ENV) PATH="$(getconf PATH)" command
  277. .fi
  278. .P
  279. .RE
  280. .P
  281. Some have suggested that
  282. .IR env
  283. is redundant since the same effect is achieved by:
  284. .sp
  285. .RS 4
  286. .nf
  287. name=value ... utility \fB[\fR argument ... \fB]\fR
  288. .fi
  289. .P
  290. .RE
  291. .P
  292. The example is equivalent to
  293. .IR env
  294. when an environment variable is being added to the environment of the
  295. command, but not when the environment is being set to the given value.
  296. The
  297. .IR env
  298. utility also writes out the current environment if invoked without
  299. arguments. There is sufficient functionality beyond what the example
  300. provides to justify inclusion of
  301. .IR env .
  302. .SH "FUTURE DIRECTIONS"
  303. None.
  304. .SH "SEE ALSO"
  305. .IR "Section 2.14" ", " "Special Built-In Utilities",
  306. .IR "Section 2.5" ", " "Parameters and Variables"
  307. .P
  308. The Base Definitions volume of POSIX.1\(hy2017,
  309. .IR "Chapter 8" ", " "Environment Variables",
  310. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  311. .\"
  312. .SH COPYRIGHT
  313. Portions of this text are reprinted and reproduced in electronic form
  314. from IEEE Std 1003.1-2017, Standard for Information Technology
  315. -- Portable Operating System Interface (POSIX), The Open Group Base
  316. Specifications Issue 7, 2018 Edition,
  317. Copyright (C) 2018 by the Institute of
  318. Electrical and Electronics Engineers, Inc and The Open Group.
  319. In the event of any discrepancy between this version and the original IEEE and
  320. The Open Group Standard, the original IEEE and The Open Group Standard
  321. is the referee document. The original Standard can be obtained online at
  322. http://www.opengroup.org/unix/online.html .
  323. .PP
  324. Any typographical or formatting errors that appear
  325. in this page are most likely
  326. to have been introduced during the conversion of the source files to
  327. man page format. To report such errors, see
  328. https://www.kernel.org/doc/man-pages/reporting_bugs.html .