<html lang="en">
<head>
<title>Process Completion - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Processes.html#Processes" title="Processes">
<link rel="prev" href="Executing-a-File.html#Executing-a-File" title="Executing a File">
<link rel="next" href="Process-Completion-Status.html#Process-Completion-Status" title="Process Completion Status">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Process-Completion"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Process-Completion-Status.html#Process-Completion-Status">Process Completion Status</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Executing-a-File.html#Executing-a-File">Executing a File</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Processes.html#Processes">Processes</a>
<hr>
</div>

<h3 class="section">26.6 Process Completion</h3>

<p><a name="index-process-completion-3178"></a><a name="index-waiting-for-completion-of-child-process-3179"></a><a name="index-testing-exit-status-of-child-process-3180"></a>
The functions described in this section are used to wait for a child
process to terminate or stop, and determine its status.  These functions
are declared in the header file <samp><span class="file">sys/wait.h</span></samp>. 
<a name="index-sys_002fwait_002eh-3181"></a>
<!-- sys/wait.h -->
<!-- POSIX.1 -->

<div class="defun">
&mdash; Function: pid_t <b>waitpid</b> (<var>pid_t pid, int *status-ptr, int options</var>)<var><a name="index-waitpid-3182"></a></var><br>
<blockquote><p>The <code>waitpid</code> function is used to request status information from a
child process whose process ID is <var>pid</var>.  Normally, the calling
process is suspended until the child process makes status information
available by terminating.

        <p>Other values for the <var>pid</var> argument have special interpretations.  A
value of <code>-1</code> or <code>WAIT_ANY</code> requests status information for
any child process; a value of <code>0</code> or <code>WAIT_MYPGRP</code> requests
information for any child process in the same process group as the
calling process; and any other negative value &minus; <var>pgid</var>
requests information for any child process whose process group ID is
<var>pgid</var>.

        <p>If status information for a child process is available immediately, this
function returns immediately without waiting.  If more than one eligible
child process has status information available, one of them is chosen
randomly, and its status is returned immediately.  To get the status
from the other eligible child processes, you need to call <code>waitpid</code>
again.

        <p>The <var>options</var> argument is a bit mask.  Its value should be the
bitwise OR (that is, the &lsquo;<samp><span class="samp">|</span></samp>&rsquo; operator) of zero or more of the
<code>WNOHANG</code> and <code>WUNTRACED</code> flags.  You can use the
<code>WNOHANG</code> flag to indicate that the parent process shouldn't wait;
and the <code>WUNTRACED</code> flag to request status information from stopped
processes as well as processes that have terminated.

        <p>The status information from the child process is stored in the object
that <var>status-ptr</var> points to, unless <var>status-ptr</var> is a null pointer.

        <p>This function is a cancellation point in multi-threaded programs.  This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <code>waitpid</code> is
called.  If the thread gets canceled these resources stay allocated
until the program ends.  To avoid this calls to <code>waitpid</code> should be
protected using cancellation handlers. 
<!-- ref pthread_cleanup_push / pthread_cleanup_pop -->

        <p>The return value is normally the process ID of the child process whose
status is reported.  If there are child processes but none of them is
waiting to be noticed, <code>waitpid</code> will block until one is.  However,
if the <code>WNOHANG</code> option was specified, <code>waitpid</code> will return
zero instead of blocking.

        <p>If a specific PID to wait for was given to <code>waitpid</code>, it will
ignore all other children (if any).  Therefore if there are children
waiting to be noticed but the child whose PID was specified is not one
of them, <code>waitpid</code> will block or return zero as described above.

        <p>A value of <code>-1</code> is returned in case of error.  The following
<code>errno</code> error conditions are defined for this function:

          <dl>
<dt><code>EINTR</code><dd>The function was interrupted by delivery of a signal to the calling
process.  See <a href="Interrupted-Primitives.html#Interrupted-Primitives">Interrupted Primitives</a>.

          <br><dt><code>ECHILD</code><dd>There are no child processes to wait for, or the specified <var>pid</var>
is not a child of the calling process.

          <br><dt><code>EINVAL</code><dd>An invalid value was provided for the <var>options</var> argument. 
</dl>
        </p></blockquote></div>

   <p>These symbolic constants are defined as values for the <var>pid</var> argument
to the <code>waitpid</code> function.

<!-- Extra blank lines make it look better. -->
     <dl>
<dt><code>WAIT_ANY</code><dd>
This constant macro (whose value is <code>-1</code>) specifies that
<code>waitpid</code> should return status information about any child process.

     <br><dt><code>WAIT_MYPGRP</code><dd>This constant (with value <code>0</code>) specifies that <code>waitpid</code> should
return status information about any child process in the same process
group as the calling process. 
</dl>

   <p>These symbolic constants are defined as flags for the <var>options</var>
argument to the <code>waitpid</code> function.  You can bitwise-OR the flags
together to obtain a value to use as the argument.

     <dl>
<dt><code>WNOHANG</code><dd>
This flag specifies that <code>waitpid</code> should return immediately
instead of waiting, if there is no child process ready to be noticed.

     <br><dt><code>WUNTRACED</code><dd>
This flag specifies that <code>waitpid</code> should report the status of any
child processes that have been stopped as well as those that have
terminated. 
</dl>

<!-- sys/wait.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Function: pid_t <b>wait</b> (<var>int *status-ptr</var>)<var><a name="index-wait-3183"></a></var><br>
<blockquote><p>This is a simplified version of <code>waitpid</code>, and is used to wait
until any one child process terminates.  The call:

     <pre class="smallexample">          wait (&amp;status)
</pre>
        <p class="noindent">is exactly equivalent to:

     <pre class="smallexample">          waitpid (-1, &amp;status, 0)
</pre>
        <p>This function is a cancellation point in multi-threaded programs.  This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <code>wait</code> is
called.  If the thread gets canceled these resources stay allocated
until the program ends.  To avoid this calls to <code>wait</code> should be
protected using cancellation handlers. 
<!-- ref pthread_cleanup_push / pthread_cleanup_pop -->
</p></blockquote></div>

<!-- sys/wait.h -->
<!-- BSD -->
<div class="defun">
&mdash; Function: pid_t <b>wait4</b> (<var>pid_t pid, int *status-ptr, int options, struct rusage *usage</var>)<var><a name="index-wait4-3184"></a></var><br>
<blockquote><p>If <var>usage</var> is a null pointer, <code>wait4</code> is equivalent to
<code>waitpid (</code><var>pid</var><code>, </code><var>status-ptr</var><code>, </code><var>options</var><code>)</code>.

        <p>If <var>usage</var> is not null, <code>wait4</code> stores usage figures for the
child process in <code>*</code><var>rusage</var> (but only if the child has
terminated, not if it has stopped).  See <a href="Resource-Usage.html#Resource-Usage">Resource Usage</a>.

        <p>This function is a BSD extension. 
</p></blockquote></div>

   <p>Here's an example of how to use <code>waitpid</code> to get the status from
all child processes that have terminated, without ever waiting.  This
function is designed to be a handler for <code>SIGCHLD</code>, the signal that
indicates that at least one child process has terminated.

<pre class="smallexample">     void
     sigchld_handler (int signum)
     {
       int pid, status, serrno;
       serrno = errno;
       while (1)
         {
           pid = waitpid (WAIT_ANY, &amp;status, WNOHANG);
           if (pid &lt; 0)
             {
               perror ("waitpid");
               break;
             }
           if (pid == 0)
             break;
           notice_termination (pid, status);
         }
       errno = serrno;
     }
</pre>
   </body></html>