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.3p (30054B)


  1. '\" et
  2. .TH POSIX_SPAWN "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,
  12. posix_spawnp
  13. \(em spawn a process
  14. (\fBADVANCED REALTIME\fP)
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <spawn.h>
  19. .P
  20. int posix_spawn(pid_t *restrict \fIpid\fP, const char *restrict \fIpath\fP,
  21. const posix_spawn_file_actions_t *\fIfile_actions\fP,
  22. const posix_spawnattr_t *restrict \fIattrp\fP,
  23. char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]);
  24. int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP,
  25. const posix_spawn_file_actions_t *\fIfile_actions\fP,
  26. const posix_spawnattr_t *restrict \fIattrp\fP,
  27. char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]);
  28. .fi
  29. .SH DESCRIPTION
  30. The
  31. \fIposix_spawn\fR()
  32. and
  33. \fIposix_spawnp\fR()
  34. functions shall create a new process (child process) from the specified
  35. process image. The new process image shall be constructed from a regular
  36. executable file called the new process image file.
  37. .P
  38. When a C program is executed as the result of this call, it shall be
  39. entered as a C-language function call as follows:
  40. .sp
  41. .RS 4
  42. .nf
  43. int main(int \fIargc\fP, char *\fIargv\fP[]);
  44. .fi
  45. .P
  46. .RE
  47. .P
  48. where
  49. .IR argc
  50. is the argument count and
  51. .IR argv
  52. is an array of character pointers to the arguments themselves. In
  53. addition, the following variable:
  54. .sp
  55. .RS 4
  56. .nf
  57. extern char **environ;
  58. .fi
  59. .P
  60. .RE
  61. .P
  62. shall be initialized as a pointer to an array of character pointers to
  63. the environment strings.
  64. .P
  65. The argument
  66. .IR argv
  67. is an array of character pointers to null-terminated strings. The last
  68. member of this array shall be a null pointer and is not
  69. counted in
  70. .IR argc .
  71. These strings constitute the argument list available to the new process
  72. image. The value in
  73. .IR argv [0]
  74. should point to a filename string that is associated with the process
  75. image being started by the
  76. \fIposix_spawn\fR()
  77. or
  78. \fIposix_spawnp\fR()
  79. function.
  80. .P
  81. The argument
  82. .IR envp
  83. is an array of character pointers to null-terminated strings. These
  84. strings constitute the environment for the new process image. The
  85. environment array is terminated by a null pointer.
  86. .P
  87. The number of bytes available for the combined argument
  88. and environment lists of the child process is
  89. {ARG_MAX}.
  90. The implementation shall specify in the system documentation (see the Base Definitions volume of POSIX.1\(hy2017,
  91. .IR "Chapter 2" ", " "Conformance")
  92. whether any list overhead, such as length words, null
  93. terminators, pointers, or alignment bytes, is included in this total.
  94. .P
  95. The
  96. .IR path
  97. argument to
  98. \fIposix_spawn\fR()
  99. is a pathname that identifies the new process image file to execute.
  100. .P
  101. The
  102. .IR file
  103. parameter to
  104. \fIposix_spawnp\fR()
  105. shall be used to construct a pathname that identifies the new process
  106. image file. If the
  107. .IR file
  108. parameter contains a
  109. <slash>
  110. character, the
  111. .IR file
  112. parameter shall be used as the pathname for the new process image
  113. file. Otherwise, the path prefix for this file shall be obtained by a
  114. search of the directories passed as the environment variable
  115. .IR PATH
  116. (see the Base Definitions volume of POSIX.1\(hy2017,
  117. .IR "Chapter 8" ", " "Environment Variables").
  118. If this environment variable is not defined, the results of the search
  119. are implementation-defined.
  120. .P
  121. If
  122. .IR file_actions
  123. is a null pointer, then file descriptors open in the calling process
  124. shall remain open in the child process, except for those whose
  125. close-on-\c
  126. .IR exec
  127. flag FD_CLOEXEC is set (see
  128. .IR "\fIfcntl\fR\^(\|)").
  129. For those file descriptors that remain open, the child process shall
  130. not inherit any file locks, but all remaining attributes of the
  131. corresponding open file descriptions (see
  132. .IR "\fIfcntl\fR\^(\|)"),
  133. shall remain unchanged.
  134. .P
  135. If
  136. .IR file_actions
  137. is not NULL, then the file descriptors open in the child process shall
  138. be those open in the calling process as modified by the spawn file
  139. actions object pointed to by
  140. .IR file_actions
  141. and the FD_CLOEXEC flag of each remaining open file descriptor after
  142. the spawn file actions have been processed. The effective order of
  143. processing the spawn file actions shall be:
  144. .IP " 1." 4
  145. The set of open file descriptors for the child process shall initially
  146. be the same set as is open for the calling process. The child process
  147. shall not inherit any file locks, but all remaining attributes of the
  148. corresponding open file descriptions (see
  149. .IR "\fIfcntl\fR\^(\|)"),
  150. shall remain unchanged.
  151. .IP " 2." 4
  152. The signal mask, signal default actions, and the effective user and
  153. group IDs for the child process shall be changed as specified in the
  154. attributes object referenced by
  155. .IR attrp .
  156. .IP " 3." 4
  157. The file actions specified by the spawn file actions object shall be
  158. performed in the order in which they were added to the spawn file
  159. actions object.
  160. .IP " 4." 4
  161. Any file descriptor that has its FD_CLOEXEC flag set (see
  162. .IR "\fIfcntl\fR\^(\|)")
  163. shall be closed.
  164. .P
  165. If file descriptor 0, 1, or 2 would otherwise be closed in the new
  166. process image created by
  167. \fIposix_spawn\fR()
  168. or
  169. \fIposix_spawnp\fR(),
  170. implementations may open an unspecified file for the file descriptor in
  171. the new process image. If a standard utility or a conforming application
  172. is executed with file descriptor 0 not open for reading or with file
  173. descriptor 1 or 2 not open for writing, the environment in which the
  174. utility or application is executed shall be deemed non-conforming, and
  175. consequently the utility or application might not behave as described
  176. in this standard.
  177. .P
  178. The
  179. .BR posix_spawnattr_t
  180. spawn attributes object type is defined in
  181. .IR <spawn.h> .
  182. It shall contain at least the attributes defined below.
  183. .P
  184. If the POSIX_SPAWN_SETPGROUP flag is set in the
  185. .IR spawn-flags
  186. attribute
  187. of the object referenced by
  188. .IR attrp ,
  189. and the
  190. .IR spawn-pgroup
  191. attribute of the same object is non-zero, then the child's process
  192. group shall be as specified in the
  193. .IR spawn-pgroup
  194. attribute of the object referenced by
  195. .IR attrp .
  196. .P
  197. As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the
  198. .IR spawn-flags
  199. attribute of the object referenced by
  200. .IR attrp ,
  201. and the
  202. .IR spawn-pgroup
  203. attribute of the same object is set to zero, then the child shall be in
  204. a new process group with a process group ID equal to its process ID.
  205. .P
  206. If the POSIX_SPAWN_SETPGROUP flag is not set in the
  207. .IR spawn-flags
  208. attribute of the object referenced by
  209. .IR attrp ,
  210. the new child process shall inherit the parent's process group.
  211. .P
  212. If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the
  213. .IR spawn-flags
  214. attribute of the object referenced by
  215. .IR attrp ,
  216. but POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall
  217. initially have the scheduling policy of the calling process with the
  218. scheduling parameters specified in the
  219. .IR spawn-schedparam
  220. attribute of the object referenced by
  221. .IR attrp .
  222. .P
  223. If the POSIX_SPAWN_SETSCHEDULER flag is set in the
  224. .IR spawn-flags
  225. attribute of the object referenced by
  226. .IR attrp
  227. (regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), the
  228. new process image shall initially have the scheduling policy specified
  229. in the
  230. .IR spawn-schedpolicy
  231. attribute of the object referenced by
  232. .IR attrp
  233. and the scheduling parameters specified in the
  234. .IR spawn-schedparam
  235. attribute of the same object.
  236. .P
  237. The POSIX_SPAWN_RESETIDS flag in the
  238. .IR spawn-flags
  239. attribute of the object referenced by
  240. .IR attrp
  241. governs the effective user ID of the child process. If this flag is
  242. not set, the child process shall inherit the effective user ID of the
  243. parent process. If this flag is set, the effective user ID of the child
  244. process shall be reset to the parent's real user ID. In either case,
  245. if the set-user-ID mode bit of the new process image file is set, the
  246. effective user ID of the child process shall become that file's owner
  247. ID before the new process image begins execution.
  248. .P
  249. The POSIX_SPAWN_RESETIDS flag in the
  250. .IR spawn-flags
  251. attribute of the object referenced by
  252. .IR attrp
  253. also governs the effective group ID of the child process. If this flag
  254. is not set, the child process shall inherit the effective group ID of the
  255. parent process. If this flag is set, the effective group ID of the child
  256. process shall be reset to the parent's real group ID. In either case,
  257. if the set-group-ID mode bit of the new process image file is set, the
  258. effective group ID of the child process shall become that file's group
  259. ID before the new process image begins execution.
  260. .P
  261. If the POSIX_SPAWN_SETSIGMASK flag is set in the
  262. .IR spawn-flags
  263. attribute of the object referenced by
  264. .IR attrp ,
  265. the child process shall initially have the signal mask specified in the
  266. .IR spawn-sigmask
  267. attribute of the object referenced by
  268. .IR attrp .
  269. .P
  270. If the POSIX_SPAWN_SETSIGDEF flag is set in the
  271. .IR spawn-flags
  272. attribute of the object referenced by
  273. .IR attrp ,
  274. the signals specified in the
  275. .IR spawn-sigdefault
  276. attribute of the same object shall be set to their default actions in
  277. the child process. Signals set to the default action in the parent
  278. process shall be set to the default action in the child process.
  279. .P
  280. Signals set to be caught by the calling process shall be set to the
  281. default action in the child process.
  282. .P
  283. Except for SIGCHLD, signals set to be ignored by the calling process
  284. image shall be set to be ignored by the child process, unless otherwise
  285. specified by the POSIX_SPAWN_SETSIGDEF flag being set in the
  286. .IR spawn-flags
  287. attribute of the object referenced by
  288. .IR attrp
  289. and the signals being indicated in the
  290. .IR spawn-sigdefault
  291. attribute of the object referenced by
  292. .IR attrp .
  293. .P
  294. If the SIGCHLD signal is set to be ignored by the calling process, it
  295. is unspecified whether the SIGCHLD signal is set to be ignored or to
  296. the default action in the child process, unless otherwise specified by
  297. the POSIX_SPAWN_SETSIGDEF flag being set in the
  298. .IR spawn_flags
  299. attribute of the object referenced by
  300. .IR attrp
  301. and the SIGCHLD signal being indicated in the
  302. .IR spawn_sigdefault
  303. attribute of the object referenced by
  304. .IR attrp .
  305. .P
  306. If the value of the
  307. .IR attrp
  308. pointer is NULL, then the default values are used.
  309. .P
  310. All process attributes, other than those influenced by the attributes
  311. set in the object referenced by
  312. .IR attrp
  313. as specified above or by the file descriptor manipulations specified in
  314. .IR file_actions ,
  315. shall appear in the new process image as though
  316. \fIfork\fR()
  317. had been called to create a child process and then a member of the
  318. .IR exec
  319. family of functions had been called by the child process to execute the
  320. new process image.
  321. .P
  322. It is implementation-defined whether the fork handlers are run when
  323. \fIposix_spawn\fR()
  324. or
  325. \fIposix_spawnp\fR()
  326. is called.
  327. .SH "RETURN VALUE"
  328. Upon successful completion,
  329. \fIposix_spawn\fR()
  330. and
  331. \fIposix_spawnp\fR()
  332. shall return the process ID of the child process to the parent process,
  333. in the variable pointed to by a non-NULL
  334. .IR pid
  335. argument, and shall return zero as the function return value.
  336. Otherwise, no child process shall be created, the value stored into the
  337. variable pointed to by a non-NULL
  338. .IR pid
  339. is unspecified, and an error number shall be returned as the function
  340. return value to indicate the error. If the
  341. .IR pid
  342. argument is a null pointer, the process ID of the child is not returned
  343. to the caller.
  344. .SH ERRORS
  345. These functions may fail if:
  346. .TP
  347. .BR EINVAL
  348. The value specified by
  349. .IR file_actions
  350. or
  351. .IR attrp
  352. is invalid.
  353. .P
  354. If this error occurs after the calling process successfully returns
  355. from the
  356. \fIposix_spawn\fR()
  357. or
  358. \fIposix_spawnp\fR()
  359. function, the child process may exit with exit status 127.
  360. .P
  361. If
  362. \fIposix_spawn\fR()
  363. or
  364. \fIposix_spawnp\fR()
  365. fail for any of the reasons that would cause
  366. \fIfork\fR()
  367. or one of the
  368. .IR exec
  369. family of functions to fail, an error value shall be returned as
  370. described by
  371. \fIfork\fR()
  372. and
  373. .IR exec ,
  374. respectively (or, if the error occurs after the calling process
  375. successfully returns, the child process shall exit with exit status 127).
  376. .P
  377. If POSIX_SPAWN_SETPGROUP is set in the
  378. .IR spawn-flags
  379. attribute of the object referenced by
  380. .IR attrp ,
  381. and
  382. \fIposix_spawn\fR()
  383. or
  384. \fIposix_spawnp\fR()
  385. fails while changing the child's process group, an error value shall be
  386. returned as described by
  387. \fIsetpgid\fR()
  388. (or, if the error occurs after the calling process successfully
  389. returns, the child process shall exit with exit status 127).
  390. .P
  391. If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not
  392. set in the
  393. .IR spawn-flags
  394. attribute of the object referenced by
  395. .IR attrp ,
  396. then if
  397. \fIposix_spawn\fR()
  398. or
  399. \fIposix_spawnp\fR()
  400. fails for any of the reasons that would cause
  401. \fIsched_setparam\fR()
  402. to fail, an error value shall be returned as described by
  403. \fIsched_setparam\fR()
  404. (or, if the error occurs after the calling process successfully
  405. returns, the child process shall exit with exit status 127).
  406. .P
  407. If POSIX_SPAWN_SETSCHEDULER is set in the
  408. .IR spawn-flags
  409. attribute of the object referenced by
  410. .IR attrp ,
  411. and if
  412. \fIposix_spawn\fR()
  413. or
  414. \fIposix_spawnp\fR()
  415. fails for any of the reasons that would cause
  416. \fIsched_setscheduler\fR()
  417. to fail, an error value shall be returned as described by
  418. \fIsched_setscheduler\fR()
  419. (or, if the error occurs after the calling process successfully
  420. returns, the child process shall exit with exit status 127).
  421. .P
  422. If the
  423. .IR file_actions
  424. argument is not NULL, and specifies any
  425. .IR close ,
  426. .IR dup2 ,
  427. or
  428. .IR open
  429. actions to be performed, and if
  430. \fIposix_spawn\fR()
  431. or
  432. \fIposix_spawnp\fR()
  433. fails for any of the reasons that would cause
  434. \fIclose\fR(),
  435. \fIdup2\fR(),
  436. or
  437. \fIopen\fR()
  438. to fail, an error value shall be returned as described by
  439. \fIclose\fR(),
  440. \fIdup2\fR(),
  441. and
  442. \fIopen\fR(),
  443. respectively (or, if the error occurs after the calling process
  444. successfully returns, the child process shall exit with exit status
  445. 127). An open file action may, by itself, result in any of the errors
  446. described by
  447. \fIclose\fR()
  448. or
  449. \fIdup2\fR(),
  450. in addition to those described by
  451. \fIopen\fR().
  452. .LP
  453. .IR "The following sections are informative."
  454. .SH EXAMPLES
  455. None.
  456. .SH "APPLICATION USAGE"
  457. These functions are part of the Spawn option and need not be
  458. provided on all implementations.
  459. .P
  460. See also the APPLICATION USAGE section for
  461. .IR "\fIexec\fR\^".
  462. .SH RATIONALE
  463. The
  464. \fIposix_spawn\fR()
  465. function and its close relation
  466. \fIposix_spawnp\fR()
  467. have been introduced to overcome the following perceived difficulties
  468. with
  469. \fIfork\fR():
  470. the
  471. \fIfork\fR()
  472. function is difficult or impossible to implement without swapping or
  473. dynamic address translation.
  474. .IP " *" 4
  475. Swapping is generally too slow for a realtime environment.
  476. .IP " *" 4
  477. Dynamic address translation is not available everywhere that POSIX
  478. might be useful.
  479. .IP " *" 4
  480. Processes are too useful to simply option out of POSIX whenever it must
  481. run without address translation or other MMU services.
  482. .P
  483. Thus, POSIX needs process creation and file execution primitives that
  484. can be efficiently implemented without address translation or other MMU
  485. services.
  486. .P
  487. The
  488. \fIposix_spawn\fR()
  489. function is implementable as a library routine, but both
  490. \fIposix_spawn\fR()
  491. and
  492. \fIposix_spawnp\fR()
  493. are designed as kernel operations. Also, although they may be an
  494. efficient replacement for many
  495. \fIfork\fR()/\c
  496. .IR exec
  497. pairs, their goal is to provide useful process creation primitives for
  498. systems that have difficulty with
  499. \fIfork\fR(),
  500. not to provide drop-in replacements for
  501. \fIfork\fR()/\c
  502. .IR exec .
  503. .P
  504. This view of the role of
  505. \fIposix_spawn\fR()
  506. and
  507. \fIposix_spawnp\fR()
  508. influenced the design of their API. It does not attempt to provide the
  509. full functionality of
  510. \fIfork\fR()/\c
  511. .IR exec
  512. in which arbitrary user-specified operations of any sort are permitted
  513. between the creation of the child process and the execution of the new
  514. process image; any attempt to reach that level would need to provide a
  515. programming language as parameters. Instead,
  516. \fIposix_spawn\fR()
  517. and
  518. \fIposix_spawnp\fR()
  519. are process creation primitives like the
  520. .IR Start_Process
  521. and
  522. .IR Start_Process_Search
  523. Ada language bindings package
  524. .IR POSIX_Process_Primitives
  525. and also like those in many operating systems that are not UNIX
  526. systems, but with some POSIX-specific additions.
  527. .P
  528. To achieve its coverage goals,
  529. \fIposix_spawn\fR()
  530. and
  531. \fIposix_spawnp\fR()
  532. have control of six types of inheritance: file descriptors, process
  533. group ID, user and group ID, signal mask, scheduling, and whether each
  534. signal ignored in the parent will remain ignored in the child, or be
  535. reset to its default action in the child.
  536. .P
  537. Control of file descriptors is required to allow an independently
  538. written child process image to access data streams opened by and even
  539. generated or read by the parent process without being specifically
  540. coded to know which parent files and file descriptors are to be used.
  541. Control of the process group ID is required to control how the
  542. job control of the child process relates to that of the parent.
  543. .P
  544. Control of the signal mask and signal defaulting is sufficient to
  545. support the implementation of
  546. \fIsystem\fR().
  547. Although support for
  548. \fIsystem\fR()
  549. is not explicitly one of the goals for
  550. \fIposix_spawn\fR()
  551. and
  552. \fIposix_spawnp\fR(),
  553. it is covered under the ``at least 50%'' coverage goal.
  554. .P
  555. The intention is that the normal file descriptor inheritance across
  556. \fIfork\fR(),
  557. the subsequent effect of the specified spawn file actions, and the
  558. normal file descriptor inheritance across one of the
  559. .IR exec
  560. family of functions should fully specify open file inheritance. The
  561. implementation need make no decisions regarding the set of open file
  562. descriptors when the child process image begins execution, those
  563. decisions having already been made by the caller and expressed as the
  564. set of open file descriptors and their FD_CLOEXEC flags at the time of
  565. the call and the spawn file actions object specified in the call. We
  566. have been assured that in cases where the POSIX
  567. .IR Start_Process
  568. Ada primitives have been implemented in a library, this method of
  569. controlling file descriptor inheritance may be implemented very easily.
  570. .P
  571. We can identify several problems with
  572. \fIposix_spawn\fR()
  573. and
  574. \fIposix_spawnp\fR(),
  575. but there does not appear to be a solution that introduces fewer
  576. problems. Environment modification for child process attributes not
  577. specifiable via the
  578. .IR attrp
  579. or
  580. .IR file_actions
  581. arguments must be done in the parent process, and since the parent
  582. generally wants to save its context, it is more costly than similar
  583. functionality with
  584. \fIfork\fR()/\c
  585. .IR exec .
  586. It is also complicated to modify the environment of a multi-threaded
  587. process temporarily, since all threads must agree when it is safe for
  588. the environment to be changed. However, this cost is only borne by
  589. those invocations of
  590. \fIposix_spawn\fR()
  591. and
  592. \fIposix_spawnp\fR()
  593. that use the additional functionality. Since extensive modifications
  594. are not the usual case, and are particularly unlikely in time-critical
  595. code, keeping much of the environment control out of
  596. \fIposix_spawn\fR()
  597. and
  598. \fIposix_spawnp\fR()
  599. is appropriate design.
  600. .P
  601. The
  602. \fIposix_spawn\fR()
  603. and
  604. \fIposix_spawnp\fR()
  605. functions do not have all the power of
  606. \fIfork\fR()/\c
  607. .IR exec .
  608. This is to be expected. The
  609. \fIfork\fR()
  610. function is a wonderfully powerful operation. We do not expect to
  611. duplicate its functionality in a simple, fast function with no special
  612. hardware requirements. It is worth noting that
  613. \fIposix_spawn\fR()
  614. and
  615. \fIposix_spawnp\fR()
  616. are very similar to the process creation operations on many operating
  617. systems that are not UNIX systems.
  618. .SS "Requirements"
  619. .P
  620. The requirements for
  621. \fIposix_spawn\fR()
  622. and
  623. \fIposix_spawnp\fR()
  624. are:
  625. .IP " *" 4
  626. They must be implementable without an MMU or unusual hardware.
  627. .IP " *" 4
  628. They must be compatible with existing POSIX standards.
  629. .P
  630. Additional goals are:
  631. .IP " *" 4
  632. They should be efficiently implementable.
  633. .IP " *" 4
  634. They should be able to replace at least 50% of typical executions of
  635. \fIfork\fR().
  636. .IP " *" 4
  637. A system with
  638. \fIposix_spawn\fR()
  639. and
  640. \fIposix_spawnp\fR()
  641. and without
  642. \fIfork\fR()
  643. should be useful, at least for realtime applications.
  644. .IP " *" 4
  645. A system with
  646. \fIfork\fR()
  647. and the
  648. .IR exec
  649. family should be able to implement
  650. \fIposix_spawn\fR()
  651. and
  652. \fIposix_spawnp\fR()
  653. as library routines.
  654. .SS "Two-Syntax"
  655. .P
  656. POSIX
  657. .IR exec
  658. has several calling sequences with approximately the same
  659. functionality. These appear to be required for compatibility with
  660. existing practice. Since the existing practice for the
  661. .IR posix_spawn* (\|)
  662. functions is otherwise substantially unlike POSIX, we feel that
  663. simplicity outweighs compatibility. There are, therefore, only two
  664. names for the
  665. .IR posix_spawn* (\|)
  666. functions.
  667. .P
  668. The parameter list does not differ between
  669. \fIposix_spawn\fR()
  670. and
  671. \fIposix_spawnp\fR();
  672. \fIposix_spawnp\fR()
  673. interprets the second parameter more elaborately than
  674. \fIposix_spawn\fR().
  675. .SS "Compatibility with POSIX.5 (Ada)"
  676. .P
  677. The
  678. .IR Start_Process
  679. and
  680. .IR Start_Process_Search
  681. procedures from the
  682. .IR POSIX_Process_Primitives
  683. package from the Ada language binding to POSIX.1 encapsulate
  684. \fIfork\fR()
  685. and
  686. .IR exec
  687. functionality in a manner similar to that of
  688. \fIposix_spawn\fR()
  689. and
  690. \fIposix_spawnp\fR().
  691. Originally, in keeping with our simplicity goal, the standard
  692. developers had limited the capabilities of
  693. \fIposix_spawn\fR()
  694. and
  695. \fIposix_spawnp\fR()
  696. to a subset of the capabilities of
  697. .IR Start_Process
  698. and
  699. .IR Start_Process_Search ;
  700. certain non-default capabilities were not supported. However, based on
  701. suggestions by the ballot group to improve file descriptor mapping or
  702. drop it, and on the advice of an Ada Language Bindings working group
  703. member, the standard developers decided that
  704. \fIposix_spawn\fR()
  705. and
  706. \fIposix_spawnp\fR()
  707. should be sufficiently powerful to implement
  708. .IR Start_Process
  709. and
  710. .IR Start_Process_Search .
  711. The rationale is that if the Ada language binding to such a primitive
  712. had already been approved as an IEEE standard, there can be little
  713. justification for not approving the functionally-equivalent parts of a
  714. C binding. The only three capabilities provided by
  715. \fIposix_spawn\fR()
  716. and
  717. \fIposix_spawnp\fR()
  718. that are not provided by
  719. .IR Start_Process
  720. and
  721. .IR Start_Process_Search
  722. are optionally specifying the child's process group ID, the set of
  723. signals to be reset to default signal handling in the child process,
  724. and the child's scheduling policy and parameters.
  725. .P
  726. For the Ada language binding for
  727. .IR Start_Process
  728. to be implemented with
  729. \fIposix_spawn\fR(),
  730. that binding would need to explicitly pass an empty signal mask and the
  731. parent's environment to
  732. \fIposix_spawn\fR()
  733. whenever the caller of
  734. .IR Start_Process
  735. allowed these arguments to default, since
  736. \fIposix_spawn\fR()
  737. does not provide such defaults. The ability of
  738. .IR Start_Process
  739. to mask user-specified signals during its execution is functionally
  740. unique to the Ada language binding and must be dealt with in the
  741. binding separately from the call to
  742. \fIposix_spawn\fR().
  743. .SS "Process Group"
  744. .P
  745. The process group inheritance field can be used to join the child
  746. process with an existing process group. By assigning a value of zero to
  747. the
  748. .IR spawn-pgroup
  749. attribute of the object referenced by
  750. .IR attrp ,
  751. the
  752. \fIsetpgid\fR()
  753. mechanism will place the child process in a new process group.
  754. .SS "Threads"
  755. .P
  756. Without the
  757. \fIposix_spawn\fR()
  758. and
  759. \fIposix_spawnp\fR()
  760. functions, systems without address translation can still use threads to
  761. give an abstraction of concurrency. In many cases, thread creation
  762. suffices, but it is not always a good substitute. The
  763. \fIposix_spawn\fR()
  764. and
  765. \fIposix_spawnp\fR()
  766. functions are considerably ``heavier'' than thread creation. Processes
  767. have several important attributes that threads do not. Even without
  768. address translation, a process may have base-and-bound memory
  769. protection. Each process has a process environment including security
  770. attributes and file capabilities, and powerful scheduling attributes.
  771. Processes abstract the behavior of non-uniform-memory-architecture
  772. multi-processors better than threads, and they are more convenient to
  773. use for activities that are not closely linked.
  774. .P
  775. The
  776. \fIposix_spawn\fR()
  777. and
  778. \fIposix_spawnp\fR()
  779. functions may not bring support for multiple processes to every
  780. configuration. Process creation is not the only piece of operating
  781. system support required to support multiple processes. The total cost
  782. of support for multiple processes may be quite high in some
  783. circumstances. Existing practice shows that support for multiple
  784. processes is uncommon and threads are common among ``tiny kernels''.
  785. There should, therefore, probably continue to be AEPs for operating
  786. systems with only one process.
  787. .SS "Asynchronous Error Notification"
  788. .P
  789. A library implementation of
  790. \fIposix_spawn\fR()
  791. or
  792. \fIposix_spawnp\fR()
  793. may not be able to detect all possible errors before it forks the child
  794. process. POSIX.1\(hy2008 provides for an error indication returned from a child
  795. process which could not successfully complete the spawn operation via a
  796. special exit status which may be detected using the status value
  797. returned by
  798. \fIwait\fR(),
  799. \fIwaitid\fR(),
  800. and
  801. \fIwaitpid\fR().
  802. .P
  803. The
  804. .IR stat_val
  805. interface and the macros used to interpret it are not well suited to
  806. the purpose of returning API errors, but they are the only path
  807. available to a library implementation. Thus, an implementation may
  808. cause the child process to exit with exit status 127 for any error
  809. detected during the spawn process after the
  810. \fIposix_spawn\fR()
  811. or
  812. \fIposix_spawnp\fR()
  813. function has successfully returned.
  814. .P
  815. The standard developers had proposed using two additional macros to
  816. interpret
  817. .IR stat_val .
  818. The first, WIFSPAWNFAIL, would have detected a status that indicated
  819. that the child exited because of an error detected during the
  820. \fIposix_spawn\fR()
  821. or
  822. \fIposix_spawnp\fR()
  823. operations rather than during actual execution of the child process
  824. image; the second, WSPAWNERRNO, would have extracted the error value if
  825. WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group
  826. strongly opposed this because it would make a library implementation of
  827. \fIposix_spawn\fR()
  828. or
  829. \fIposix_spawnp\fR()
  830. dependent on kernel modifications to
  831. \fIwaitpid\fR()
  832. to be able to embed special information in
  833. .IR stat_val
  834. to indicate a spawn failure.
  835. .P
  836. The 8 bits of child process exit status that are guaranteed by POSIX.1\(hy2008 to
  837. be accessible to the waiting parent process are insufficient to
  838. disambiguate a spawn error from any other kind of error that may be
  839. returned by an arbitrary process image. No other bits of the exit
  840. status are required to be visible in
  841. .IR stat_val ,
  842. so these macros could not be strictly implemented at the library level.
  843. Reserving an exit status of 127 for such spawn errors is consistent
  844. with the use of this value by
  845. \fIsystem\fR()
  846. and
  847. \fIpopen\fR()
  848. to signal failures in these operations that occur after the function
  849. has returned but before a shell is able to execute. The exit status of
  850. 127 does not uniquely identify this class of error, nor does it provide
  851. any detailed information on the nature of the failure. Note that a
  852. kernel implementation of
  853. \fIposix_spawn\fR()
  854. or
  855. \fIposix_spawnp\fR()
  856. is permitted (and encouraged) to return any possible error as the
  857. function value, thus providing more detailed failure information to the
  858. parent process.
  859. .P
  860. Thus, no special macros are available to isolate asynchronous
  861. \fIposix_spawn\fR()
  862. or
  863. \fIposix_spawnp\fR()
  864. errors. Instead, errors detected by the
  865. \fIposix_spawn\fR()
  866. or
  867. \fIposix_spawnp\fR()
  868. operations in the context of the child process before the new process
  869. image executes are reported by setting the child's exit status to 127.
  870. The calling process may use the WIFEXITED and WEXITSTATUS macros on the
  871. .IR stat_val
  872. stored by the
  873. \fIwait\fR()
  874. or
  875. \fIwaitpid\fR()
  876. functions to detect spawn failures to the extent that other status
  877. values with which the child process image may exit (before the parent
  878. can conclusively determine that the child process image has begun
  879. execution) are distinct from exit status 127.
  880. .SH "FUTURE DIRECTIONS"
  881. None.
  882. .SH "SEE ALSO"
  883. .ad l
  884. .IR "\fIalarm\fR\^(\|)",
  885. .IR "\fIchmod\fR\^(\|)",
  886. .IR "\fIclose\fR\^(\|)",
  887. .IR "\fIdup\fR\^(\|)",
  888. .IR "\fIexec\fR\^",
  889. .IR "\fIexit\fR\^(\|)",
  890. .IR "\fIfcntl\fR\^(\|)",
  891. .IR "\fIfork\fR\^(\|)",
  892. .IR "\fIfstatat\fR\^(\|)",
  893. .IR "\fIkill\fR\^(\|)",
  894. .IR "\fIopen\fR\^(\|)",
  895. .IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)",
  896. .IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)",
  897. .IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)",
  898. .IR "\fIposix_spawnattr_destroy\fR\^(\|)",
  899. .IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)",
  900. .IR "\fIposix_spawnattr_getflags\fR\^(\|)",
  901. .IR "\fIposix_spawnattr_getpgroup\fR\^(\|)",
  902. .IR "\fIposix_spawnattr_getschedparam\fR\^(\|)",
  903. .IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)",
  904. .IR "\fIposix_spawnattr_getsigmask\fR\^(\|)",
  905. .IR "\fIsched_setparam\fR\^(\|)",
  906. .IR "\fIsched_setscheduler\fR\^(\|)",
  907. .IR "\fIsetpgid\fR\^(\|)",
  908. .IR "\fIsetuid\fR\^(\|)",
  909. .IR "\fItimes\fR\^(\|)",
  910. .IR "\fIwait\fR\^(\|)",
  911. .IR "\fIwaitid\fR\^(\|)"
  912. .ad b
  913. .P
  914. The Base Definitions volume of POSIX.1\(hy2017,
  915. .IR "Chapter 8" ", " "Environment Variables",
  916. .IR "\fB<spawn.h>\fP"
  917. .\"
  918. .SH COPYRIGHT
  919. Portions of this text are reprinted and reproduced in electronic form
  920. from IEEE Std 1003.1-2017, Standard for Information Technology
  921. -- Portable Operating System Interface (POSIX), The Open Group Base
  922. Specifications Issue 7, 2018 Edition,
  923. Copyright (C) 2018 by the Institute of
  924. Electrical and Electronics Engineers, Inc and The Open Group.
  925. In the event of any discrepancy between this version and the original IEEE and
  926. The Open Group Standard, the original IEEE and The Open Group Standard
  927. is the referee document. The original Standard can be obtained online at
  928. http://www.opengroup.org/unix/online.html .
  929. .PP
  930. Any typographical or formatting errors that appear
  931. in this page are most likely
  932. to have been introduced during the conversion of the source files to
  933. man page format. To report such errors, see
  934. https://www.kernel.org/doc/man-pages/reporting_bugs.html .