waitpid.html 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142
  1. <html>
  2. <head>
  3. <title>waitpid</title>
  4. <body bgcolor=#ffffff>
  5. <h2 align=center>waitpid</h2>
  6. <h4 align=center>OS/161 Reference Manual</h4>
  7. <h3>Name</h3>
  8. waitpid - wait for a process to exit
  9. <h3>Library</h3>
  10. Standard C Library (libc, -lc)
  11. <h3>Synopsis</h3>
  12. #include &lt;sys/wait.h&gt;<br>
  13. <br>
  14. pid_t<br>
  15. waitpid(pid_t <em>pid</em>, int *<em>status</em>, int <em>options</em>);
  16. <h3>Description</h3>
  17. Wait for the process specified by <em>pid</em> to exit, and return an
  18. encoded exit status in the integer pointed to by <em>status</em>. If
  19. that process has exited already, waitpid returns immediately. If that
  20. process does not exist, waitpid fails.
  21. <p>
  22. What it means for a process to move from "has exited already" to "does
  23. not exist", and when this occurs, is something you must decide.
  24. <p>
  25. If process P is "interested" in the exit code of process Q, process P
  26. should be able to find out that exit code by calling waitpid, even if
  27. Q exits somewhat before the time P calls waitpid. As described under
  28. <A HREF=_exit.html>_exit()</A>, precisely what is meant by "interested"
  29. is up to you.
  30. <p>
  31. You might implement restrictions or requirements on who may wait
  32. for which processes, like Unix does. You might also add a system
  33. call for one process to express interest in another process's exit
  34. code. If you do this, be sure to write a man page for the system
  35. call, and discuss the rationale for your choices therein in your
  36. design document.
  37. <p>
  38. Note that in the absence of restrictions on who may wait for what, it
  39. is possible to set up situations that may result in deadlock. Your
  40. system must (of course) in some manner protect itself from these
  41. situations, either by prohibiting them or by detecting and resolving
  42. them.
  43. <p>
  44. In order to make the userlevel code that ships with OS/161 work, assume
  45. that a parent process is always interested in the exit codes of its
  46. child processes generated with <A HREF=fork.html>fork()</A>, unless it
  47. does something special to indicate otherwise.
  48. <p>
  49. The <em>options</em> argument should be 0. You are not required to
  50. implement any options. (However, your system should check to make sure
  51. that options you do not support are not requested.)
  52. <p>
  53. If you desire, you may implement the Unix option WNOHANG; this causes
  54. waitpid, when called for a process that has not yet exited, to return
  55. 0 immediately instead of waiting.
  56. <p>
  57. The Unix option WUNTRACED, to ask for reporting of processes that stop
  58. as well as exit, is also defined in the header files, but implementing
  59. this feature is not required or necessary unless you are implementing
  60. job control.
  61. <p>
  62. You may also make up your own options if you find them helpful.
  63. However, please, document anything you make up.
  64. <p>
  65. The encoding of the exit status is comparable to Unix and is defined
  66. by the flags found in &lt;kern/wait.h&gt;. (Userlevel code should
  67. include &lt;sys/wait.h&gt; to get these definitions.) A process can
  68. exit by calling <A HREF=_exit.html>_exit()</A> or it can exit by
  69. receiving a fatal signal. In the former case the
  70. <tt>_MKWAIT_EXIT()</tt> macro should be used with the user-supplied
  71. exit code to prepare the exit status; in the latter, the
  72. <tt>_MKWAIT_SIG()</tt> macro (or <tt>_MKWAIT_CORE()</tt> if a core
  73. file was generated) should be used with the signal number. The result
  74. encoding also allows notification of processes that have stopped; this
  75. would be used in connection with job control and with
  76. <tt>ptrace</tt>-based debugging if you were to implement those things.
  77. <p>
  78. To <em>read</em> the wait status, use the macros <tt>WIFEXITED()</tt>,
  79. <tt>WIFSIGNALED()</tt>, and/or <tt>WIFSTOPPED()</tt> to find out what
  80. happened, and then <tt>WEXITSTATUS()</tt>, <tt>WTERMSIG()</tt>, or
  81. <tt>WSTOPSIG()</tt> respectively to get the exit code or signal
  82. number. If <tt>WIFSIGNALED()</tt> is true, <tt>WCOREDUMP()</tt> can be
  83. used to check if a core file was generated. This is the same as Unix,
  84. although the value encoding is different from the historic Unix
  85. format.
  86. <p>
  87. <h3>Return Values</h3>
  88. waitpid returns the process id whose exit status is reported in
  89. <em>status</em>. In OS/161, this is always the value of <em>pid</em>.
  90. <p>
  91. If you implement WNOHANG, and WNOHANG is given, and the process
  92. specified by <em>pid</em> has not yet exited, waitpid returns 0.
  93. <p>
  94. (In Unix, but not by default OS/161, you can wait for any of several
  95. processes by passing magic values of <em>pid</em>, so this return
  96. value can actually be useful.)
  97. <p>
  98. On error, -1 is returned, and errno is set to a suitable error code
  99. for the error condition encountered.
  100. <h3>Errors</h3>
  101. The following error codes should be returned under the conditions
  102. given. Other error codes may be returned for other errors not
  103. mentioned here.
  104. <blockquote><table width=90%>
  105. <td width=10%>&nbsp;</td><td>&nbsp;</td></tr>
  106. <tr><td>EINVAL</td> <td>The <em>options</em> argument requested invalid or
  107. unsupported options.</td></tr>
  108. <tr><td>ECHILD</td> <td>The <em>pid</em> argument named a process
  109. that the current process was not interested
  110. in or that has not yet exited.</td></tr>
  111. <tr><td>ESRCH</td> <td>The <em>pid</em> argument named a
  112. nonexistent process.</td></tr>
  113. <tr><td>EFAULT</td> <td>The <em>status</em> argument was an
  114. invalid pointer.</td></tr>
  115. </table></blockquote>
  116. </body>
  117. </html>