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

posix_spawn_file_actions_addclose.3p (11024B)


  1. '\" et
  2. .TH POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE "3P" 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. posix_spawn_file_actions_addclose,
  12. posix_spawn_file_actions_addopen
  13. \(em add close or open action to spawn file actions object
  14. (\fBADVANCED REALTIME\fP)
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <spawn.h>
  19. .P
  20. int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
  21. *\fIfile_actions\fP, int \fIfildes\fP);
  22. int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
  23. *restrict \fIfile_actions\fP, int \fIfildes\fP,
  24. const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. These functions shall add or delete a close or open action to a
  28. spawn file actions object.
  29. .P
  30. A spawn file actions object is of type
  31. .BR posix_spawn_file_actions_t
  32. (defined in
  33. .IR <spawn.h> )
  34. and is used to specify a series of actions to be performed by a
  35. \fIposix_spawn\fR()
  36. or
  37. \fIposix_spawnp\fR()
  38. operation in order to arrive at the set of open file descriptors for
  39. the child process given the set of open file descriptors of the parent.
  40. POSIX.1\(hy2008 does not define comparison or assignment operators for the type
  41. .BR posix_spawn_file_actions_t .
  42. .P
  43. A spawn file actions object, when passed to
  44. \fIposix_spawn\fR()
  45. or
  46. \fIposix_spawnp\fR(),
  47. shall specify how the set of open file descriptors in the calling
  48. process is transformed into a set of potentially open file descriptors
  49. for the spawned process. This transformation shall be as if the
  50. specified sequence of actions was performed exactly once, in the
  51. context of the spawned process (prior to execution of the new process
  52. image), in the order in which the actions were added to the object;
  53. additionally, when the new process image is executed, any file
  54. descriptor (from this new set) which has its FD_CLOEXEC
  55. flag set shall be closed (see
  56. .IR "\fIposix_spawn\fR\^(\|)").
  57. .P
  58. The
  59. \fIposix_spawn_file_actions_addclose\fR()
  60. function shall add a
  61. .IR close
  62. action to the object referenced by
  63. .IR file_actions
  64. that shall cause the file descriptor
  65. .IR fildes
  66. to be closed (as if
  67. .IR close (\c
  68. .IR fildes )
  69. had been called) when a new process is spawned using this file actions
  70. object.
  71. .P
  72. The
  73. \fIposix_spawn_file_actions_addopen\fR()
  74. function shall add an
  75. .IR open
  76. action to the object referenced by
  77. .IR file_actions
  78. that shall cause the file named by
  79. .IR path
  80. to be opened (as if
  81. .IR open (\c
  82. .IR path ,
  83. .IR oflag ,
  84. .IR mode )
  85. had been called, and the returned file descriptor, if not
  86. .IR fildes ,
  87. had been changed to
  88. .IR fildes )
  89. when a new process is spawned using this file actions object. If
  90. .IR fildes
  91. was already an open file descriptor, it shall be closed before the new
  92. file is opened.
  93. .P
  94. The string described by
  95. .IR path
  96. shall be copied by the
  97. \fIposix_spawn_file_actions_addopen\fR()
  98. function.
  99. .SH "RETURN VALUE"
  100. Upon successful completion, these functions shall return zero;
  101. otherwise, an error number shall be returned to indicate the error.
  102. .SH ERRORS
  103. The
  104. \fIposix_spawn_file_actions_addopen\fR()
  105. function shall fail if:
  106. .TP
  107. .BR EBADF
  108. The value specified by
  109. .IR fildes
  110. is negative or greater than or equal to
  111. {OPEN_MAX}.
  112. .P
  113. The
  114. \fIposix_spawn_file_actions_addclose\fR()
  115. function shall fail if:
  116. .TP
  117. .BR EBADF
  118. The value specified by
  119. .IR fildes
  120. is negative.
  121. .br
  122. .P
  123. These functions may fail if:
  124. .TP
  125. .BR EINVAL
  126. The value specified by
  127. .IR file_actions
  128. is invalid.
  129. .TP
  130. .BR ENOMEM
  131. Insufficient memory exists to add to the spawn file actions object.
  132. .P
  133. It shall not be considered an error for the
  134. .IR fildes
  135. argument passed to these functions to specify a file descriptor for
  136. which the specified operation could not be performed at the time of the
  137. call. Any such error will be detected when the associated file actions
  138. object is later used during a
  139. \fIposix_spawn\fR()
  140. or
  141. \fIposix_spawnp\fR()
  142. operation.
  143. .LP
  144. .IR "The following sections are informative."
  145. .SH EXAMPLES
  146. None.
  147. .SH "APPLICATION USAGE"
  148. These functions are part of the Spawn option and need not be provided
  149. on all implementations.
  150. .P
  151. Implementations may use file descriptors that must be inherited into
  152. child processes for the child process to remain conforming, such as for
  153. message catalog or tracing purposes. Therefore, an application that calls
  154. \fIposix_spawn_file_actions_addclose\fR()
  155. with an arbitrary integer risks non-conforming behavior, and this
  156. function can only portably be used to close file descriptor values that
  157. the application has obtained through explicit actions, or for the three
  158. file descriptors corresponding to the standard file streams. In order
  159. to avoid a race condition of leaking an unintended file descriptor
  160. into a child process, an application should consider opening all file
  161. descriptors with the FD_CLOEXEC bit set unless the file descriptor is
  162. intended to be inherited across
  163. .IR exec .
  164. .SH RATIONALE
  165. A spawn file actions object may be initialized to contain an ordered
  166. sequence of
  167. \fIclose\fR(),
  168. \fIdup2\fR(),
  169. and
  170. \fIopen\fR()
  171. operations to be used by
  172. \fIposix_spawn\fR()
  173. or
  174. \fIposix_spawnp\fR()
  175. to arrive at the set of open file descriptors inherited by the spawned
  176. process from the set of open file descriptors in the parent at the time
  177. of the
  178. \fIposix_spawn\fR()
  179. or
  180. \fIposix_spawnp\fR()
  181. call. It had been suggested that the
  182. \fIclose\fR()
  183. and
  184. \fIdup2\fR()
  185. operations alone are sufficient to rearrange file descriptors, and that
  186. files which need to be opened for use by the spawned process can be
  187. handled either by having the calling process open them before the
  188. \fIposix_spawn\fR()
  189. or
  190. \fIposix_spawnp\fR()
  191. call (and close them after), or by passing pathnames to the spawned
  192. process (in
  193. .IR argv )
  194. so that it may open them itself. The standard developers recommend that
  195. applications use one of these two methods when practical, since
  196. detailed error status on a failed open operation is always available to
  197. the application this way. However, the standard developers feel that
  198. allowing a spawn file actions object to specify open operations is
  199. still appropriate because:
  200. .IP " 1." 4
  201. It is consistent with equivalent POSIX.5 (Ada) functionality.
  202. .IP " 2." 4
  203. It supports the I/O redirection paradigm commonly employed by POSIX
  204. programs designed to be invoked from a shell. When such a program is
  205. the child process, it may not be designed to open files on its own.
  206. .IP " 3." 4
  207. It allows file opens that might otherwise fail or violate file
  208. ownership/access rights if executed by the parent process.
  209. .P
  210. Regarding 2. above, note that the spawn open file action provides to
  211. \fIposix_spawn\fR()
  212. and
  213. \fIposix_spawnp\fR()
  214. the same capability that the shell redirection operators provide to
  215. \fIsystem\fR(),
  216. only without the intervening execution of a shell; for example:
  217. .sp
  218. .RS 4
  219. .nf
  220. system ("myprog <file1 3<file2");
  221. .fi
  222. .P
  223. .RE
  224. .P
  225. Regarding 3. above, note that if the calling process needs to open one
  226. or more files for access by the spawned process, but has insufficient
  227. spare file descriptors, then the open action is necessary to allow the
  228. \fIopen\fR()
  229. to occur in the context of the child process after other file
  230. descriptors have been closed (that must remain open in the parent).
  231. .P
  232. Additionally, if a parent is executed from a file having a
  233. ``set-user-id'' mode bit set and the POSIX_SPAWN_RESETIDS flag is set
  234. in the spawn attributes, a file created within the parent process will
  235. (possibly incorrectly) have the parent's effective user ID as its
  236. owner, whereas a file created via an
  237. \fIopen\fR()
  238. action during
  239. \fIposix_spawn\fR()
  240. or
  241. \fIposix_spawnp\fR()
  242. will have the parent's real ID as its owner; and an open by the parent
  243. process may successfully open a file to which the real user should not
  244. have access or fail to open a file to which the real user should have
  245. access.
  246. .SS "File Descriptor Mapping"
  247. .P
  248. The standard developers had originally proposed using an array which
  249. specified the mapping of child file descriptors back to those of the
  250. parent. It was pointed out by the ballot group that it is not possible
  251. to reshuffle file descriptors arbitrarily in a library implementation
  252. of
  253. \fIposix_spawn\fR()
  254. or
  255. \fIposix_spawnp\fR()
  256. without provision for one or more spare file descriptor entries (which
  257. simply may not be available). Such an array requires that an
  258. implementation develop a complex strategy to achieve the desired
  259. mapping without inadvertently closing the wrong file descriptor at the
  260. wrong time.
  261. .P
  262. It was noted by a member of the Ada Language Bindings working group
  263. that the approved Ada Language
  264. .IR Start_Process
  265. family of POSIX process primitives use a caller-specified set of file
  266. actions to alter the normal
  267. \fIfork\fR()/\c
  268. .IR exec
  269. semantics for inheritance of file descriptors in a very flexible way,
  270. yet no such problems exist because the burden of determining how to
  271. achieve the final file descriptor mapping is completely on the
  272. application. Furthermore, although the file actions interface appears
  273. frightening at first glance, it is actually quite simple to implement
  274. in either a library or the kernel.
  275. .P
  276. The
  277. \fIposix_spawn_file_actions_addclose\fR()
  278. function is not required to check whether the file descriptor is less than
  279. {OPEN_MAX}
  280. because on some implementations
  281. {OPEN_MAX}
  282. reflects the RLIMIT_NOFILE soft limit and therefore calling
  283. \fIsetrlimit\fR()
  284. to reduce this limit can result in an
  285. {OPEN_MAX}
  286. value less than or equal to an already open file descriptor.
  287. Applications need to be able to close such file descriptors on spawn.
  288. On implementations where
  289. {OPEN_MAX}
  290. does not change, it is recommended that
  291. \fIposix_spawn_file_actions_addclose\fR()
  292. should return
  293. .BR [EBADF]
  294. if
  295. .IR fildes
  296. is greater than or equal to
  297. {OPEN_MAX}.
  298. .SH "FUTURE DIRECTIONS"
  299. None.
  300. .SH "SEE ALSO"
  301. .ad l
  302. .IR "\fIclose\fR\^(\|)",
  303. .IR "\fIdup\fR\^(\|)",
  304. .IR "\fIopen\fR\^(\|)",
  305. .IR "\fIposix_spawn\fR\^(\|)",
  306. .IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)",
  307. .IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)"
  308. .ad b
  309. .P
  310. The Base Definitions volume of POSIX.1\(hy2017,
  311. .IR "\fB<spawn.h>\fP"
  312. .\"
  313. .SH COPYRIGHT
  314. Portions of this text are reprinted and reproduced in electronic form
  315. from IEEE Std 1003.1-2017, Standard for Information Technology
  316. -- Portable Operating System Interface (POSIX), The Open Group Base
  317. Specifications Issue 7, 2018 Edition,
  318. Copyright (C) 2018 by the Institute of
  319. Electrical and Electronics Engineers, Inc and The Open Group.
  320. In the event of any discrepancy between this version and the original IEEE and
  321. The Open Group Standard, the original IEEE and The Open Group Standard
  322. is the referee document. The original Standard can be obtained online at
  323. http://www.opengroup.org/unix/online.html .
  324. .PP
  325. Any typographical or formatting errors that appear
  326. in this page are most likely
  327. to have been introduced during the conversion of the source files to
  328. man page format. To report such errors, see
  329. https://www.kernel.org/doc/man-pages/reporting_bugs.html .