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

wait.3p (25358B)


  1. '\" et
  2. .TH WAIT "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. wait,
  12. waitpid
  13. \(em wait for a child process to stop or terminate
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/wait.h>
  18. .P
  19. pid_t wait(int *\fIstat_loc\fP);
  20. pid_t waitpid(pid_t \fIpid\fP, int *\fIstat_loc\fP, int \fIoptions\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIwait\fR()
  25. and
  26. \fIwaitpid\fR()
  27. functions shall obtain status information (see
  28. .IR "Section 2.13" ", " "Status Information")
  29. pertaining to one of the caller's child processes. The
  30. \fIwait\fR()
  31. function obtains status information for process termination from
  32. any child process. The
  33. \fIwaitpid\fR()
  34. function obtains status information for process termination, and
  35. optionally process stop and/or continue, from a specified subset of
  36. the child processes.
  37. .P
  38. The
  39. \fIwait\fR()
  40. function shall cause the calling thread to become blocked until status
  41. information generated by child process termination is made available
  42. to the thread, or until delivery of a signal whose action is either to
  43. execute a signal-catching function or to terminate the process, or an
  44. error occurs. If termination status information is available prior to
  45. the call to
  46. \fIwait\fR(),
  47. return shall be immediate. If termination status information is
  48. available for two or more child processes, the order in which their
  49. status is reported is unspecified.
  50. .P
  51. As described in
  52. .IR "Section 2.13" ", " "Status Information",
  53. the
  54. \fIwait\fR()
  55. and
  56. \fIwaitpid\fR()
  57. functions consume the status information they obtain.
  58. .P
  59. The behavior when multiple threads are blocked in
  60. \fIwait\fR(),
  61. \fIwaitid\fR(),
  62. or
  63. \fIwaitpid\fR()
  64. is described in
  65. .IR "Section 2.13" ", " "Status Information".
  66. .P
  67. The
  68. \fIwaitpid\fR()
  69. function shall be equivalent to
  70. \fIwait\fR()
  71. if the
  72. .IR pid
  73. argument is (\fBpid_t\fP)\-1 and the
  74. .IR options
  75. argument is 0. Otherwise, its behavior shall be modified by the values
  76. of the
  77. .IR pid
  78. and
  79. .IR options
  80. arguments.
  81. .P
  82. The
  83. .IR pid
  84. argument specifies a set of child processes for which
  85. .IR status
  86. is requested. The
  87. \fIwaitpid\fR()
  88. function shall only return the status of a child process from this set:
  89. .IP " *" 4
  90. If
  91. .IR pid
  92. is equal to (\fBpid_t\fP)\-1,
  93. .IR status
  94. is requested for any child process. In this respect,
  95. \fIwaitpid\fR()
  96. is then equivalent to
  97. \fIwait\fR().
  98. .IP " *" 4
  99. If
  100. .IR pid
  101. is greater than 0, it specifies the process ID of a single child
  102. process for which
  103. .IR status
  104. is requested.
  105. .IP " *" 4
  106. If
  107. .IR pid
  108. is 0,
  109. .IR status
  110. is requested for any child process whose process group ID is equal to
  111. that of the calling process.
  112. .IP " *" 4
  113. If
  114. .IR pid
  115. is less than (\fBpid_t\fP)\-1,
  116. .IR status
  117. is requested for any child process whose process group ID is equal to
  118. the absolute value of
  119. .IR pid .
  120. .P
  121. The
  122. .IR options
  123. argument is constructed from the bitwise-inclusive OR of zero or more
  124. of the following flags, defined in the
  125. .IR <sys/wait.h>
  126. header:
  127. .IP WCONTINUED 12
  128. The
  129. \fIwaitpid\fR()
  130. function shall report the status of any continued child process
  131. specified by
  132. .IR pid
  133. whose status has not been reported since it continued from a job
  134. control stop.
  135. .IP WNOHANG 12
  136. The
  137. \fIwaitpid\fR()
  138. function shall not suspend execution of the calling thread if
  139. .IR status
  140. is not immediately available for one of the child processes specified
  141. by
  142. .IR pid .
  143. .IP WUNTRACED 12
  144. The status of any child processes specified by
  145. .IR pid
  146. that are stopped, and whose status has not yet been reported since they
  147. stopped, shall also be reported to the requesting process.
  148. .P
  149. If
  150. \fIwait\fR()
  151. or
  152. \fIwaitpid\fR()
  153. return because the status of a child process is available, these
  154. functions shall return a value equal to the process ID of the child
  155. process. In this case, if the value of the argument
  156. .IR stat_loc
  157. is not a null pointer, information shall be stored in the location
  158. pointed to by
  159. .IR stat_loc .
  160. The value stored at the location pointed to by
  161. .IR stat_loc
  162. shall be 0 if and only if the status returned is from a terminated
  163. child process that terminated by one of the following means:
  164. .IP " 1." 4
  165. The process returned 0 from
  166. \fImain\fR().
  167. .IP " 2." 4
  168. The process called
  169. \fI_exit\fR()
  170. or
  171. \fIexit\fR()
  172. with a
  173. .IR status
  174. argument of 0.
  175. .IP " 3." 4
  176. The process was terminated because the last thread in the process
  177. terminated.
  178. .P
  179. Regardless of its value, this information may be
  180. interpreted using the following macros, which are defined in
  181. .IR <sys/wait.h>
  182. and evaluate to integral expressions; the
  183. .IR stat_val
  184. argument is the integer value pointed to by
  185. .IR stat_loc .
  186. .IP "WIFEXITED(\fIstat_val\fP)" 6
  187. .br
  188. Evaluates to a non-zero value if
  189. .IR status
  190. was returned for a child process that terminated normally.
  191. .IP "WEXITSTATUS(\fIstat_val\fP)" 6
  192. .br
  193. If the value of WIFEXITED(\fIstat_val\fP) is non-zero, this macro
  194. evaluates to the low-order 8 bits of the
  195. .IR status
  196. argument that the child process passed to
  197. \fI_exit\fR()
  198. or
  199. \fIexit\fR(),
  200. or the value the child process returned from
  201. \fImain\fR().
  202. .IP "WIFSIGNALED(\fIstat_val\fP)" 6
  203. .br
  204. Evaluates to a non-zero value if
  205. .IR status
  206. was returned for a child process that terminated due to the receipt of
  207. a signal that was not caught (see
  208. .IR <signal.h> ).
  209. .IP "WTERMSIG(\fIstat_val\fP)" 6
  210. .br
  211. If the value of WIFSIGNALED(\fIstat_val\fP) is non-zero, this macro
  212. evaluates to the number of the signal that caused the termination of
  213. the child process.
  214. .IP "WIFSTOPPED(\fIstat_val\fP)" 6
  215. .br
  216. Evaluates to a non-zero value if
  217. .IR status
  218. was returned for a child process that is currently stopped.
  219. .IP "WSTOPSIG(\fIstat_val\fP)" 6
  220. .br
  221. If the value of WIFSTOPPED(\fIstat_val\fP) is non-zero, this macro
  222. evaluates to the number of the signal that caused the child process to
  223. stop.
  224. .IP "WIFCONTINUED(\fIstat_val\fP)" 6
  225. .br
  226. Evaluates to a non-zero value if
  227. .IR status
  228. was returned for a child process that has continued from a job control
  229. stop.
  230. .P
  231. It is unspecified whether the
  232. .IR status
  233. value returned by calls to
  234. \fIwait\fR()
  235. or
  236. \fIwaitpid\fR()
  237. for processes created by
  238. \fIposix_spawn\fR()
  239. or
  240. \fIposix_spawnp\fR()
  241. can indicate a WIFSTOPPED(\fIstat_val\fP) before subsequent calls to
  242. \fIwait\fR()
  243. or
  244. \fIwaitpid\fR()
  245. indicate WIFEXITED(\fIstat_val\fP) as the result of an error detected
  246. before the new process image starts executing.
  247. .P
  248. It is unspecified whether the
  249. .IR status
  250. value returned by calls to
  251. \fIwait\fR()
  252. or
  253. \fIwaitpid\fR()
  254. for processes created by
  255. \fIposix_spawn\fR()
  256. or
  257. \fIposix_spawnp\fR()
  258. can indicate a WIFSIGNALED(\fIstat_val\fP) if a signal is sent to the
  259. parent's process group after
  260. \fIposix_spawn\fR()
  261. or
  262. \fIposix_spawnp\fR()
  263. is called.
  264. .P
  265. If the information pointed to by
  266. .IR stat_loc
  267. was stored by a call to
  268. \fIwaitpid\fR()
  269. that specified the WUNTRACED flag
  270. and did not specify the WCONTINUED flag,
  271. exactly one of the macros WIFEXITED(*\fIstat_loc\fR),
  272. WIFSIGNALED(*\fIstat_loc\fR), and WIFSTOPPED(*\fIstat_loc\fR)
  273. shall evaluate to a non-zero value.
  274. .P
  275. If the information pointed to by
  276. .IR stat_loc
  277. was stored by a call to
  278. \fIwaitpid\fR()
  279. that specified the WUNTRACED and WCONTINUED flags, exactly one
  280. of the macros WIFEXITED(*\fIstat_loc\fR),
  281. WIFSIGNALED(*\fIstat_loc\fR), WIFSTOPPED(*\fIstat_loc\fR),
  282. and WIFCONTINUED(*\fIstat_loc\fR) shall evaluate to a non-zero value.
  283. .P
  284. If the information pointed to by
  285. .IR stat_loc
  286. was stored by a call to
  287. \fIwaitpid\fR()
  288. that did not specify the WUNTRACED
  289. or WCONTINUED
  290. flags, or by a call to the
  291. \fIwait\fR()
  292. function, exactly one of the macros WIFEXITED(*\fIstat_loc\fR) and
  293. WIFSIGNALED(*\fIstat_loc\fR) shall evaluate to a non-zero value.
  294. .P
  295. If the information pointed to by
  296. .IR stat_loc
  297. was stored by a call to
  298. \fIwaitpid\fR()
  299. that did not specify the WUNTRACED flag and specified the WCONTINUED flag,
  300. exactly one of the macros WIFEXITED(*\fIstat_loc\fR),
  301. WIFSIGNALED(*\fIstat_loc\fR), and WIFCONTINUED(*\fIstat_loc\fR)
  302. shall evaluate to a non-zero value.
  303. .P
  304. If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues
  305. the SIGCHLD signal, then if
  306. \fIwait\fR()
  307. or
  308. \fIwaitpid\fR()
  309. returns because the status of a child process is available, any pending
  310. SIGCHLD signal associated with the process ID of the child process
  311. shall be discarded. Any other pending SIGCHLD signals shall remain
  312. pending.
  313. .P
  314. Otherwise, if SIGCHLD is blocked, if
  315. \fIwait\fR()
  316. or
  317. \fIwaitpid\fR()
  318. return because the status of a child process is available, any pending
  319. SIGCHLD signal shall be cleared unless the status of another child
  320. process is available.
  321. .P
  322. For all other conditions, it is unspecified whether child
  323. .IR status
  324. will be available when a SIGCHLD signal is delivered.
  325. .P
  326. There may be additional implementation-defined circumstances under
  327. which
  328. \fIwait\fR()
  329. or
  330. \fIwaitpid\fR()
  331. report
  332. .IR status .
  333. This shall not occur unless the calling process or one of its child
  334. processes explicitly makes use of a non-standard extension. In these
  335. cases the interpretation of the reported
  336. .IR status
  337. is implementation-defined.
  338. .P
  339. If a parent process terminates without waiting for all of its child
  340. processes to terminate, the remaining child processes shall be assigned
  341. a new parent process ID corresponding to an implementation-defined
  342. system process.
  343. .SH "RETURN VALUE"
  344. If
  345. \fIwait\fR()
  346. or
  347. \fIwaitpid\fR()
  348. returns because the status of a child process is available, these
  349. functions shall return a value equal to the process ID of the child
  350. process for which
  351. .IR status
  352. is reported. If
  353. \fIwait\fR()
  354. or
  355. \fIwaitpid\fR()
  356. returns due to the delivery of a signal to the calling process, \-1
  357. shall be returned and
  358. .IR errno
  359. set to
  360. .BR [EINTR] .
  361. If
  362. \fIwaitpid\fR()
  363. was invoked with WNOHANG set in
  364. .IR options ,
  365. it has at least one child process specified by
  366. .IR pid
  367. for which
  368. .IR status
  369. is not available, and
  370. .IR status
  371. is not available for any process specified by
  372. .IR pid ,
  373. 0 is returned. Otherwise, \-1 shall be returned, and
  374. .IR errno
  375. set to indicate the error.
  376. .SH ERRORS
  377. The
  378. \fIwait\fR()
  379. function shall fail if:
  380. .TP
  381. .BR ECHILD
  382. The calling process has no existing unwaited-for child processes.
  383. .TP
  384. .BR EINTR
  385. The function was interrupted by a signal. The value of the location
  386. pointed to by
  387. .IR stat_loc
  388. is undefined.
  389. .P
  390. The
  391. \fIwaitpid\fR()
  392. function shall fail if:
  393. .TP
  394. .BR ECHILD
  395. The process specified by
  396. .IR pid
  397. does not exist or is not a child of the calling process, or the process
  398. group specified by
  399. .IR pid
  400. does not exist or does not have any member process that is a child of
  401. the calling process.
  402. .TP
  403. .BR EINTR
  404. The function was interrupted by a signal. The value of the location
  405. pointed to by
  406. .IR stat_loc
  407. is undefined.
  408. .TP
  409. .BR EINVAL
  410. The
  411. .IR options
  412. argument is not valid.
  413. .LP
  414. .IR "The following sections are informative."
  415. .SH EXAMPLES
  416. .SS "Waiting for a Child Process and then Checking its Status"
  417. .P
  418. The following example demonstrates the use of
  419. \fIwaitpid\fR(),
  420. \fIfork\fR(),
  421. and the macros used to interpret the status value returned by
  422. \fIwaitpid\fR()
  423. (and
  424. \fIwait\fR()).
  425. The code segment creates a child process which does some unspecified
  426. work. Meanwhile the parent loops performing calls to
  427. \fIwaitpid\fR()
  428. to monitor the status of the child. The loop terminates when child
  429. termination is detected.
  430. .sp
  431. .RS 4
  432. .nf
  433. #include <stdio.h>
  434. #include <stdlib.h>
  435. #include <unistd.h>
  436. #include <sys/wait.h>
  437. \&...
  438. .P
  439. pid_t child_pid, wpid;
  440. int status;
  441. .P
  442. child_pid = fork();
  443. if (child_pid == -1) { /* fork() failed */
  444. perror("fork");
  445. exit(EXIT_FAILURE);
  446. }
  447. .P
  448. if (child_pid == 0) { /* This is the child */
  449. /* Child does some work and then terminates */
  450. ...
  451. .P
  452. } else { /* This is the parent */
  453. do {
  454. wpid = waitpid(child_pid, &status, WUNTRACED
  455. #ifdef WCONTINUED /* Not all implementations support this */
  456. | WCONTINUED
  457. #endif
  458. );
  459. if (wpid == -1) {
  460. perror("waitpid");
  461. exit(EXIT_FAILURE);
  462. }
  463. .P
  464. if (WIFEXITED(status)) {
  465. printf("child exited, status=%d\en", WEXITSTATUS(status));
  466. .P
  467. } else if (WIFSIGNALED(status)) {
  468. printf("child killed (signal %d)\en", WTERMSIG(status));
  469. .P
  470. } else if (WIFSTOPPED(status)) {
  471. printf("child stopped (signal %d)\en", WSTOPSIG(status));
  472. .P
  473. #ifdef WIFCONTINUED /* Not all implementations support this */
  474. } else if (WIFCONTINUED(status)) {
  475. printf("child continued\en");
  476. #endif
  477. } else { /* Non-standard case -- may never happen */
  478. printf("Unexpected status (0x%x)\en", status);
  479. }
  480. } while (!WIFEXITED(status) && !WIFSIGNALED(status));
  481. }
  482. .fi
  483. .P
  484. .RE
  485. .SS "Waiting for a Child Process in a Signal Handler for SIGCHLD"
  486. .P
  487. The following example demonstrates how to use
  488. \fIwaitpid\fR()
  489. in a signal handler for SIGCHLD without passing \-1 as the
  490. .IR pid
  491. argument. (See the APPLICATION USAGE section below for the reasons
  492. why passing a
  493. .IR pid
  494. of \-1 is not recommended.) The method used here relies on the
  495. standard behavior of
  496. \fIwaitpid\fR()
  497. when SIGCHLD is blocked. On historical non-conforming systems, the
  498. status of some child processes might not be reported.
  499. .sp
  500. .RS 4
  501. .nf
  502. #include <stdlib.h>
  503. #include <stdio.h>
  504. #include <signal.h>
  505. #include <sys/types.h>
  506. #include <sys/wait.h>
  507. #include <unistd.h>
  508. .P
  509. #define CHILDREN 10
  510. .P
  511. static void
  512. handle_sigchld(int signum, siginfo_t *sinfo, void *unused)
  513. {
  514. int sav_errno = errno;
  515. int status;
  516. .P
  517. /*
  518. * Obtain status information for the child which
  519. * caused the SIGCHLD signal and write its exit code
  520. * to stdout.
  521. */
  522. if (sinfo->si_code != CLD_EXITED)
  523. {
  524. static char msg[] = "wrong si_code\en";
  525. write(2, msg, sizeof msg - 1);
  526. }
  527. else if (waitpid(sinfo->si_pid, &status, 0) =\|= -1)
  528. {
  529. static char msg[] = "waitpid() failed\en";
  530. write(2, msg, sizeof msg - 1);
  531. }
  532. else if (!WIFEXITED(status))
  533. {
  534. static char msg[] = "WIFEXITED was false\en";
  535. write(2, msg, sizeof msg - 1);
  536. }
  537. else
  538. {
  539. int code = WEXITSTATUS(status);
  540. char buf[2];
  541. buf[0] = \(aq0\(aq + code;
  542. buf[1] = \(aq\en\(aq;
  543. write(1, buf, 2);
  544. }
  545. errno = sav_errno;
  546. }
  547. .P
  548. int
  549. main(void)
  550. {
  551. int i;
  552. pid_t pid;
  553. struct sigaction sa;
  554. .P
  555. sa.sa_flags = SA_SIGINFO;
  556. sa.sa_sigaction = handle_sigchld;
  557. sigemptyset(&sa.sa_mask);
  558. if (sigaction(SIGCHLD, &sa, NULL) =\|= -1)
  559. {
  560. perror("sigaction");
  561. exit(EXIT_FAILURE);
  562. }
  563. .P
  564. for (i = 0; i < CHILDREN; i++)
  565. {
  566. switch (pid = fork())
  567. {
  568. case -1:
  569. perror("fork");
  570. exit(EXIT_FAILURE);
  571. case 0:
  572. sleep(2);
  573. _exit(i);
  574. }
  575. }
  576. .P
  577. /* Wait for all the SIGCHLD signals, then terminate on SIGALRM */
  578. alarm(3);
  579. for (;;)
  580. pause();
  581. .P
  582. return 0; /* NOTREACHED */
  583. }
  584. .fi
  585. .P
  586. .RE
  587. .SH "APPLICATION USAGE"
  588. Calls to
  589. \fIwait\fR()
  590. will collect information about any child process. This may result in
  591. interactions with other interfaces that may be waiting for their own
  592. children (such as by use of
  593. \fIsystem\fR()).
  594. For this and other reasons it is recommended that portable applications
  595. not use
  596. \fIwait\fR(),
  597. but instead use
  598. \fIwaitpid\fR().
  599. For these same reasons, the use of
  600. \fIwaitpid\fR()
  601. with a
  602. .IR pid
  603. argument of \-1, and the use of
  604. \fIwaitid\fR()
  605. with the
  606. .IR idtype
  607. argument set to P_ALL, are also not recommended for portable applications.
  608. .P
  609. As specified in
  610. .IR "Consequences of Process Termination",
  611. if the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
  612. SIG_IGN, then the termination of a child process will not cause status
  613. information to become available to a thread blocked in
  614. \fIwait\fR(),
  615. \fIwaitid\fR(),
  616. or
  617. \fIwaitpid\fR().
  618. Thus, a thread blocked in one of the wait functions will remain
  619. blocked unless some other condition causes the thread to resume
  620. execution (such as an
  621. .BR [ECHILD]
  622. failure due to no remaining children in the set of waited-for children).
  623. .SH RATIONALE
  624. A call to the
  625. \fIwait\fR()
  626. or
  627. \fIwaitpid\fR()
  628. function only returns
  629. .IR status
  630. on an immediate child process of the calling process; that is, a child
  631. that was produced by a single
  632. \fIfork\fR()
  633. call (perhaps followed by an
  634. .IR exec
  635. or other function calls) from the parent. If a child produces
  636. grandchildren by further use of
  637. \fIfork\fR(),
  638. none of those grandchildren nor any of their descendants affect the
  639. behavior of a
  640. \fIwait\fR()
  641. from the original parent process. Nothing in this volume of POSIX.1\(hy2017 prevents an
  642. implementation from providing extensions that permit a process to get
  643. .IR status
  644. from a grandchild or any other process, but a process that does not use
  645. such extensions must be guaranteed to see
  646. .IR status
  647. from only its direct children.
  648. .P
  649. The
  650. \fIwaitpid\fR()
  651. function is provided for three reasons:
  652. .IP " 1." 4
  653. To support job control
  654. .IP " 2." 4
  655. To permit a non-blocking version of the
  656. \fIwait\fR()
  657. function
  658. .IP " 3." 4
  659. To permit a library routine, such as
  660. \fIsystem\fR()
  661. or
  662. \fIpclose\fR(),
  663. to wait for its children without interfering with other terminated
  664. children for which the process has not waited
  665. .P
  666. The first two of these facilities are based on the
  667. .IR wait3 (\|)
  668. function provided by 4.3 BSD. The function uses the
  669. .IR options
  670. argument, which is equivalent to an argument to
  671. .IR wait3 (\|).
  672. The WUNTRACED
  673. flag is used only in conjunction with job control on systems supporting
  674. job control. Its name comes from 4.3 BSD
  675. and refers to the fact that there are two types of stopped processes in
  676. that implementation: processes being traced via the
  677. \fIptrace\fR()
  678. debugging facility and (untraced) processes stopped by job control
  679. signals. Since
  680. \fIptrace\fR()
  681. is not part of this volume of POSIX.1\(hy2017, only the second type is relevant. The name
  682. WUNTRACED was retained because its usage is the same, even though the
  683. name is not intuitively meaningful in this context.
  684. .P
  685. The third reason for the
  686. \fIwaitpid\fR()
  687. function is to permit independent sections of a process to spawn and
  688. wait for children without interfering with each other. For example,
  689. the following problem occurs in developing a portable shell, or command
  690. interpreter:
  691. .sp
  692. .RS 4
  693. .nf
  694. stream = popen("/bin/true");
  695. (void) system("sleep 100");
  696. (void) pclose(stream);
  697. .fi
  698. .P
  699. .RE
  700. .P
  701. On all historical implementations, the final
  702. \fIpclose\fR()
  703. fails to reap the
  704. \fIwait\fR()
  705. .IR status
  706. of the
  707. \fIpopen\fR().
  708. .P
  709. The status values are retrieved by macros, rather than given as
  710. specific bit encodings as they are in most historical implementations
  711. (and thus expected by existing programs). This was necessary to
  712. eliminate a limitation on the number of signals an implementation can
  713. support that was inherent in the traditional encodings. This volume of POSIX.1\(hy2017
  714. does require that a
  715. .IR status
  716. value of zero corresponds to a process calling
  717. .IR _exit (0),
  718. as this is the most common encoding expected by existing programs.
  719. Some of the macro names were adopted from 4.3 BSD.
  720. .P
  721. These macros syntactically operate on an arbitrary integer value. The
  722. behavior is undefined unless that value is one stored by a successful
  723. call to
  724. \fIwait\fR()
  725. or
  726. \fIwaitpid\fR()
  727. in the location pointed to by the
  728. .IR stat_loc
  729. argument. An early proposal attempted to make this clearer by specifying
  730. each argument as *\fIstat_loc\fP rather than
  731. .IR stat_val .
  732. However, that did not follow the conventions of other specifications in
  733. \&this volume of POSIX.1\(hy2017 or traditional usage. It also could have implied that the
  734. argument to the macro must literally be *\fIstat_loc\fP; in fact, that
  735. value can be stored or passed as an argument to other functions before
  736. being interpreted by these macros.
  737. .P
  738. The extension that affects
  739. \fIwait\fR()
  740. and
  741. \fIwaitpid\fR()
  742. and is common in historical implementations is the
  743. \fIptrace\fR()
  744. function. It is called by a child process and causes that child to
  745. stop and return a
  746. .IR status
  747. that appears identical to the
  748. .IR status
  749. indicated by WIFSTOPPED.
  750. The
  751. .IR status
  752. of
  753. \fIptrace\fR()
  754. children is traditionally returned regardless of the WUNTRACED
  755. flag (or by the
  756. \fIwait\fR()
  757. function). Most applications do not need to concern themselves with
  758. such extensions because they have control over what extensions they or
  759. their children use. However, applications, such as command
  760. interpreters, that invoke arbitrary processes may see this behavior
  761. when those arbitrary processes misuse such extensions.
  762. .P
  763. Implementations that support
  764. .BR core
  765. file creation or other implementation-defined actions on termination
  766. of some processes traditionally provide a bit in the
  767. .IR status
  768. returned by
  769. \fIwait\fR()
  770. to indicate that such actions have occurred.
  771. .P
  772. Allowing the
  773. \fIwait\fR()
  774. family of functions to discard a pending SIGCHLD signal that is
  775. associated with a successfully waited-for child process puts them into
  776. the
  777. \fIsigwait\fR()
  778. and
  779. \fIsigwaitinfo\fR()
  780. category with respect to SIGCHLD.
  781. .P
  782. This definition allows implementations to treat a pending SIGCHLD
  783. signal as accepted by the process in
  784. \fIwait\fR(),
  785. with the same meaning of ``accepted'' as when that word is applied to
  786. the
  787. \fIsigwait\fR()
  788. family of functions.
  789. .P
  790. Allowing the
  791. \fIwait\fR()
  792. family of functions to behave this way permits an implementation to be
  793. able to deal precisely with SIGCHLD signals.
  794. .P
  795. In particular, an implementation that does accept (discard) the SIGCHLD
  796. signal can make the following guarantees regardless of the queuing
  797. depth of signals in general (the list of waitable children can hold the
  798. SIGCHLD queue):
  799. .IP " 1." 4
  800. If a SIGCHLD signal handler is established via
  801. \fIsigaction\fR()
  802. without the SA_RESETHAND flag, SIGCHLD signals can be accurately
  803. counted; that is, exactly one SIGCHLD signal will be delivered to or
  804. accepted by the process for every child process that terminates.
  805. .IP " 2." 4
  806. A single
  807. \fIwait\fR()
  808. issued from a SIGCHLD signal handler can be guaranteed to return
  809. immediately with status information for a child process.
  810. .IP " 3." 4
  811. When SA_SIGINFO is requested, the SIGCHLD signal handler can be
  812. guaranteed to receive a non-null pointer to a
  813. .BR siginfo_t
  814. structure that describes a child process for which a wait via
  815. \fIwaitpid\fR()
  816. or
  817. \fIwaitid\fR()
  818. will not block or fail.
  819. .IP " 4." 4
  820. The
  821. \fIsystem\fR()
  822. function will not cause the SIGCHLD handler of a process to be
  823. called as a result of the
  824. \fIfork\fR()/\c
  825. .IR exec
  826. executed within
  827. \fIsystem\fR()
  828. because
  829. \fIsystem\fR()
  830. will accept the SIGCHLD signal when it performs a
  831. \fIwaitpid\fR()
  832. for its child process. This is a desirable behavior of
  833. \fIsystem\fR()
  834. so that it can be used in a library without causing side-effects to the
  835. application linked with the library.
  836. .P
  837. An implementation that does not permit the
  838. \fIwait\fR()
  839. family of functions to accept (discard) a pending SIGCHLD signal
  840. associated with a successfully waited-for child, cannot make the
  841. guarantees described above for the following reasons:
  842. .IP "Guarantee #1" 6
  843. .br
  844. Although it might be assumed that reliable queuing of all SIGCHLD
  845. signals generated by the system can make this guarantee, the
  846. counter-example is the case of a process that blocks SIGCHLD and
  847. performs an indefinite loop of
  848. \fIfork\fR()/\c
  849. \fIwait\fR()
  850. operations. If the implementation supports queued signals, then
  851. eventually the system will run out of memory for the queue. The
  852. guarantee cannot be made because there must be some limit to the depth
  853. of queuing.
  854. .IP "Guarantees #2 and #3" 6
  855. .br
  856. These cannot be guaranteed unless the
  857. \fIwait\fR()
  858. family of functions accepts the SIGCHLD signal. Otherwise, a
  859. \fIfork\fR()/\c
  860. \fIwait\fR()
  861. executed while SIGCHLD is blocked (as in the
  862. \fIsystem\fR()
  863. function) will result in an invocation of the handler when SIGCHLD is
  864. unblocked, after the process has disappeared.
  865. .IP "Guarantee #4" 6
  866. .br
  867. Although possible to make this guarantee,
  868. \fIsystem\fR()
  869. would have to set the SIGCHLD handler to SIG_DFL so that the SIGCHLD
  870. signal generated by its
  871. \fIfork\fR()
  872. would be discarded (the SIGCHLD default action is to be ignored), then
  873. restore it to its previous setting. This would have the undesirable
  874. side-effect of discarding all SIGCHLD signals pending to the process.
  875. .SH "FUTURE DIRECTIONS"
  876. None.
  877. .SH "SEE ALSO"
  878. .IR "Section 2.13" ", " "Status Information",
  879. .IR "\fIexec\fR\^",
  880. .IR "\fIexit\fR\^(\|)",
  881. .IR "\fIfork\fR\^(\|)",
  882. .IR "\fIsystem\fR\^(\|)",
  883. .IR "\fIwaitid\fR\^(\|)"
  884. .P
  885. The Base Definitions volume of POSIX.1\(hy2017,
  886. .IR "Section 4.12" ", " "Memory Synchronization",
  887. .IR "\fB<signal.h>\fP",
  888. .IR "\fB<sys_wait.h>\fP"
  889. .\"
  890. .SH COPYRIGHT
  891. Portions of this text are reprinted and reproduced in electronic form
  892. from IEEE Std 1003.1-2017, Standard for Information Technology
  893. -- Portable Operating System Interface (POSIX), The Open Group Base
  894. Specifications Issue 7, 2018 Edition,
  895. Copyright (C) 2018 by the Institute of
  896. Electrical and Electronics Engineers, Inc and The Open Group.
  897. In the event of any discrepancy between this version and the original IEEE and
  898. The Open Group Standard, the original IEEE and The Open Group Standard
  899. is the referee document. The original Standard can be obtained online at
  900. http://www.opengroup.org/unix/online.html .
  901. .PP
  902. Any typographical or formatting errors that appear
  903. in this page are most likely
  904. to have been introduced during the conversion of the source files to
  905. man page format. To report such errors, see
  906. https://www.kernel.org/doc/man-pages/reporting_bugs.html .