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

waitid.3p (7294B)


  1. '\" et
  2. .TH WAITID "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. waitid
  12. \(em wait for a child process to change state
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/wait.h>
  17. .P
  18. int waitid(idtype_t \fIidtype\fP, id_t \fIid\fP, siginfo_t *\fIinfop\fP, int \fIoptions\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIwaitid\fR()
  23. function shall obtain status information (see
  24. .IR "Section 2.13" ", " "Status Information")
  25. pertaining to termination, stop, and/or continue events in one of the
  26. caller's child processes.
  27. .P
  28. The
  29. \fIwaitid\fR()
  30. function shall cause the calling thread to become blocked until an
  31. error occurs or status information becomes available to the calling
  32. thread that satisfies all of the following properties (``matching status
  33. information''):
  34. .IP " *" 4
  35. The status information is from one of the child processes in the set
  36. of child processes specified by the
  37. .IR idtype
  38. and
  39. .IR id
  40. arguments.
  41. .IP " *" 4
  42. The state change in the status information matches one of the state
  43. change flags set in the
  44. .IR options
  45. argument.
  46. .P
  47. If matching status information is available prior to the call to
  48. \fIwaitid\fR(),
  49. return shall be immediate. If matching status information is available
  50. for two or more child processes, the order in which their status is
  51. reported is unspecified.
  52. .P
  53. As described in
  54. .IR "Section 2.13" ", " "Status Information",
  55. the
  56. \fIwaitid\fR()
  57. function consumes the status information it obtains unless the
  58. WNOWAIT flag is set in the
  59. .IR options
  60. argument.
  61. .P
  62. The behavior when multiple threads are blocked in
  63. \fIwait\fR(),
  64. \fIwaitid\fR(),
  65. or
  66. \fIwaitpid\fR()
  67. is described in
  68. .IR "Section 2.13" ", " "Status Information".
  69. .P
  70. The
  71. \fIwaitid\fR()
  72. function shall record the obtained status information in the structure
  73. pointed to by
  74. .IR infop .
  75. The fields of the structure pointed to by
  76. .IR infop
  77. shall be filled in as described under ``Pointer to a Function'' in
  78. .IR "Section 2.4.3" ", " "Signal Actions".
  79. .P
  80. The
  81. .IR idtype
  82. and
  83. .IR id
  84. arguments are used to specify which children
  85. \fIwaitid\fR()
  86. waits for.
  87. .P
  88. If
  89. .IR idtype
  90. is P_PID,
  91. \fIwaitid\fR()
  92. shall wait for the child with a process ID equal to
  93. (\fBpid_t\fP)\fIid\fR.
  94. .P
  95. If
  96. .IR idtype
  97. is P_PGID,
  98. \fIwaitid\fR()
  99. shall wait for any child with a process group ID equal to
  100. (\fBpid_t\fP)\fIid\fR.
  101. .P
  102. If
  103. .IR idtype
  104. is P_ALL,
  105. \fIwaitid\fR()
  106. shall wait for any children and
  107. .IR id
  108. is ignored.
  109. .P
  110. The
  111. .IR options
  112. argument is used to specify which state changes
  113. \fIwaitid\fR()
  114. shall wait for. It is formed by OR'ing together the following flags:
  115. .IP WCONTINUED 12
  116. Status shall be returned for any continued child process whose status
  117. either has not been reported since it continued from a job control stop
  118. or has been reported only by calls to
  119. \fIwaitid\fR()
  120. with the WNOWAIT flag set.
  121. .IP WEXITED 12
  122. Wait for processes that have exited.
  123. .IP WNOHANG 12
  124. Do not hang if no status is available; return immediately.
  125. .IP WNOWAIT 12
  126. Keep the process whose status is returned in
  127. .IR infop
  128. in a waitable state. This shall not affect the state of the process; the
  129. process may be waited for again after this call completes.
  130. .IP WSTOPPED 12
  131. Status shall be returned for any child that has stopped upon receipt of
  132. a signal, and whose status either has not been reported since it stopped
  133. or has been reported only by calls to
  134. \fIwaitid\fR()
  135. with the WNOWAIT flag set.
  136. .P
  137. Applications shall specify at least one of the flags WEXITED, WSTOPPED,
  138. or WCONTINUED to be OR'ed in with the
  139. .IR options
  140. argument.
  141. .P
  142. The application shall ensure that the
  143. .IR infop
  144. argument points to a
  145. .BR siginfo_t
  146. structure. If
  147. \fIwaitid\fR()
  148. returns because a child process was found that satisfied the conditions
  149. indicated by the arguments
  150. .IR idtype
  151. and
  152. .IR options ,
  153. then the structure pointed to by
  154. .IR infop
  155. shall be filled in by the system with the status of the process; the
  156. .IR si_signo
  157. member shall be set equal to SIGCHLD.
  158. If
  159. \fIwaitid\fR()
  160. returns because WNOHANG was specified and status is not available for
  161. any process specified by
  162. .IR idtype
  163. and
  164. .IR id ,
  165. then the
  166. .IR si_signo
  167. and
  168. .IR si_pid
  169. members of the structure pointed to by
  170. .IR infop
  171. shall be set to zero and the values of other members of the structure
  172. are unspecified.
  173. .SH "RETURN VALUE"
  174. If WNOHANG was specified and status is not available for any process
  175. specified by
  176. .IR idtype
  177. and
  178. .IR id ,
  179. 0 shall be returned. If
  180. \fIwaitid\fR()
  181. returns due to the change of state of one of its children, 0 shall be
  182. returned. Otherwise, \-1 shall be returned and
  183. .IR errno
  184. set to indicate the error.
  185. .SH ERRORS
  186. The
  187. \fIwaitid\fR()
  188. function shall fail if:
  189. .TP
  190. .BR ECHILD
  191. The calling process has no existing unwaited-for child processes.
  192. .TP
  193. .BR EINTR
  194. The
  195. \fIwaitid\fR()
  196. function was interrupted by a signal.
  197. .TP
  198. .BR EINVAL
  199. An invalid value was specified for
  200. .IR options ,
  201. or
  202. .IR idtype
  203. and
  204. .IR id
  205. specify an invalid set of processes.
  206. .LP
  207. .IR "The following sections are informative."
  208. .SH EXAMPLES
  209. None.
  210. .SH "APPLICATION USAGE"
  211. Calls to
  212. \fIwaitid\fR()
  213. with
  214. .IR idtype
  215. equal to P_ALL will collect information about any child process. This
  216. may result in interactions with other interfaces that may be waiting
  217. for their own children (such as by use of
  218. \fIsystem\fR()).
  219. For this reason it is recommended that portable applications not use
  220. \fIwaitid\fR()
  221. with idtype of P_ALL. See also APPLICATION USAGE for
  222. \fIwait\fR().
  223. .P
  224. As specified in
  225. .IR "Consequences of Process Termination",
  226. if the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
  227. SIG_IGN, then the termination of a child process will not cause status
  228. information to become available to a thread blocked in
  229. \fIwait\fR(),
  230. \fIwaitid\fR(),
  231. or
  232. \fIwaitpid\fR().
  233. Thus, a thread blocked in one of the wait functions will remain
  234. blocked unless some other condition causes the thread to resume
  235. execution (such as an
  236. .BR [ECHILD]
  237. failure due to no remaining children in the set of waited-for children).
  238. .SH RATIONALE
  239. None.
  240. .SH "FUTURE DIRECTIONS"
  241. None.
  242. .SH "SEE ALSO"
  243. .IR "Section 2.4.3" ", " "Signal Actions",
  244. .IR "Section 2.13" ", " "Status Information",
  245. .IR "\fIexec\fR\^",
  246. .IR "\fIexit\fR\^(\|)",
  247. .IR "\fIwait\fR\^(\|)"
  248. .P
  249. The Base Definitions volume of POSIX.1\(hy2017,
  250. .IR "\fB<signal.h>\fP",
  251. .IR "\fB<sys_wait.h>\fP"
  252. .\"
  253. .SH COPYRIGHT
  254. Portions of this text are reprinted and reproduced in electronic form
  255. from IEEE Std 1003.1-2017, Standard for Information Technology
  256. -- Portable Operating System Interface (POSIX), The Open Group Base
  257. Specifications Issue 7, 2018 Edition,
  258. Copyright (C) 2018 by the Institute of
  259. Electrical and Electronics Engineers, Inc and The Open Group.
  260. In the event of any discrepancy between this version and the original IEEE and
  261. The Open Group Standard, the original IEEE and The Open Group Standard
  262. is the referee document. The original Standard can be obtained online at
  263. http://www.opengroup.org/unix/online.html .
  264. .PP
  265. Any typographical or formatting errors that appear
  266. in this page are most likely
  267. to have been introduced during the conversion of the source files to
  268. man page format. To report such errors, see
  269. https://www.kernel.org/doc/man-pages/reporting_bugs.html .