<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.
<P>
<DL COMPACT>
<DT><CODE>WNOHANG</CODE>
<DD><P>
This flag specifies that <CODE>waitpid</CODE> should return immediately
instead of waiting, if there is no child process ready to be noticed.
<P>
<DT><CODE>WUNTRACED</CODE>
<DD><P>
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>
<P>
<A NAME="IDX1716"></A>
<U>Function:</U> pid_t <B>wait</B> <I>(int *<VAR>status_ptr</VAR>)</I><P>
This is a simplified version of <CODE>waitpid</CODE>, and is used to wait
until any one child process terminates.  The call:
<P>
<PRE>
wait (&#38;status)
</PRE>
<P>
is exactly equivalent to:
<P>
<PRE>
waitpid (-1, &#38;status, 0)
</PRE>
<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.
<P>
<PRE>
void
sigchld_handler (int signum)
{
  int pid;
  int status;
  while (1)
    {
      pid = waitpid (WAIT_ANY, &#38;status, WNOHANG);
      if (pid &#60; 0)
        {
          perror ("waitpid");
          break;
        }
      if (pid == 0)
        break;
      notice_termination (pid, status);
    }
}
</PRE>
<P>
<H2><A NAME="SEC408" HREF="library_toc.html#SEC408" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC408">Process Completion Status</A></H2>
<P>
If the exit status value (see section <A HREF="library_22.html#SEC395" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC395">Program Termination</A>) of the child
process is zero, then the status value reported by <CODE>waitpid</CODE> or
<CODE>wait</CODE> is also zero.  You can test for other kinds of information
encoded in the returned status value using the following macros.
These macros are defined in the header file <TT>`sys/wait.h'</TT>.
<A NAME="IDX1717"></A>
<P>
<A NAME="IDX1718"></A>
<U>Macro:</U> int <B>WIFEXITED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
normally with <CODE>exit</CODE> or <CODE>_exit</CODE>.
<P>
<A NAME="IDX1719"></A>
<U>Macro:</U> int <B>WEXITSTATUS</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFEXITED</CODE> is true of <VAR>status</VAR>, this macro returns the
low-order 8 bits of the exit status value from the child process.
See section <A HREF="library_22.html#SEC397" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC397">Exit Status</A>.
<P>
<A NAME="IDX1720"></A>
<U>Macro:</U> int <B>WIFSIGNALED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
because it received a signal that was not handled.
See section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>.
<P>
<A NAME="IDX1721"></A>
<U>Macro:</U> int <B>WTERMSIG</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFSIGNALED</CODE> is true of <VAR>status</VAR>, this macro returns the
signal number of the signal that terminated the child process.
<P>
<A NAME="IDX1722"></A>
<U>Macro:</U> int <B>WCOREDUMP</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
and produced a core dump.
<P>
<A NAME="IDX1723"></A>
<U>Macro:</U> int <B>WIFSTOPPED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process is stopped.
<P>
<A NAME="IDX1724"></A>
<U>Macro:</U> int <B>WSTOPSIG</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFSTOPPED</CODE> is true of <VAR>status</VAR>, this macro returns the
signal number of the signal that caused the child process to stop.
<P>
<H2><A NAME="SEC409" HREF="library_toc.html#SEC409" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC409">BSD Process Wait Functions</A></H2>
<P>
The GNU library also provides these related facilities for compatibility
with BSD Unix.  BSD uses the <CODE>union wait</CODE> data type to represent
status values rather than an <CODE>int</CODE>.  The two representations are
actually interchangeable; they describe the same bit patterns.  The GNU
C Library defines macros such as <CODE>WEXITSTATUS</CODE> so that they will
work on either kind of object, and the <CODE>wait</CODE> function is defined
to accept either type of pointer as its <VAR>status_ptr</VAR> argument.
<P>
These functions are declared in <TT>`sys/wait.h'</TT>.
<A NAME="IDX1725"></A>
<P>
<A NAME="IDX1726"></A>
<U>Data Type:</U> <B>union wait</B><P>
This data type represents program termination status values.  It has
the following members:
<P>
<DL COMPACT>
<DT><CODE>int w_termsig</CODE>
<DD>This member is equivalent to the <CODE>WTERMSIG</CODE> macro.
<P>
<DT><CODE>int w_coredump</CODE>
<DD>This member is equivalent to the <CODE>WCOREDUMP</CODE> macro.
<P>
<DT><CODE>int w_retcode</CODE>
<DD>This member is equivalent to the <CODE>WEXISTATUS</CODE> macro.
<P>
<DT><CODE>int w_stopsig</CODE>
<DD>This member is equivalent to the <CODE>WSTOPSIG</CODE> macro.
</DL>
<P>
Instead of accessing these members directly, you should use the
equivalent macros.
<P>
<A NAME="IDX1727"></A>
<U>Function:</U> pid_t <B>wait3</B> <I>(union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</I><P>
If <VAR>usage</VAR> is a null pointer, <CODE>wait3</CODE> is equivalent to
<CODE>waitpid (-1, <VAR>status_ptr</VAR>, <VAR>options</VAR>)</CODE>.
<P>
If <VAR>usage</VAR> is not null, <CODE>wait3</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped).  See section <A HREF="library_19.html#SEC323" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC323">Resource Usage</A>.
<P>
<A NAME="IDX1728"></A>
<U>Function:</U> pid_t <B>wait4</B> <I>(pid_t <VAR>pid</VAR>, union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</I><P>
If <VAR>usage</VAR> is a null pointer, <CODE>wait4</CODE> is equivalent to
<CODE>waitpid (<VAR>pid</VAR>, <VAR>status_ptr</VAR>, <VAR>options</VAR>)</CODE>.
<P>
If <VAR>usage</VAR> is not null, <CODE>wait4</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped).  See section <A HREF="library_19.html#SEC323" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC323">Resource Usage</A>.
<P>
<H2><A NAME="SEC410" HREF="library_toc.html#SEC410" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC410">Process Creation Example</A></H2>
<P>
Here is an example program showing how you might write a function
similar to the built-in <CODE>system</CODE>.  It executes its <VAR>command</VAR>
argument using the equivalent of <SAMP>`sh -c <VAR>command</VAR>'</SAMP>.
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/wait.h&#62;

/* Execute the command using this shell program.  */
#define SHELL "/bin/sh"

int 
my_system (const char *command)
{
  int status;
  pid_t pid;

  pid = fork ();
  if (pid == 0)
    {
      /* This is the child process.  Execute the shell command. */
      execl (SHELL, SHELL, "-c", command, NULL);
      _exit (EXIT_FAILURE);
    }
  else if (pid &#60; 0)
    /* The fork failed.  Report failure.  */
    status = -1;
  else
    /* This is the parent process.  Wait for the child to complete.  */
    if (waitpid (pid, &#38;status, 0) != pid)
      status = -1;
  return status;
}
</PRE>
<P>
There are a couple of things you should pay attention to in this
example.
<P>
Remember that the first <CODE>argv</CODE> argument supplied to the program
represents the name of the program being executed.  That is why, in the
call to <CODE>execl</CODE>, <CODE>SHELL</CODE> is supplied once to name the program
to execute and a second time to supply a value for <CODE>argv[0]</CODE>.  
<P>
The <CODE>execl</CODE> call in the child process doesn't return if it is
successful.  If it fails, you must do something to make the child
process terminate.  Just returning a bad status code with <CODE>return</CODE>
would leave two processes running the original program.  Instead, the
right behavior is for the child process to report failure to its parent
process.
<P>
Call <CODE>_exit</CODE> to accomplish this.  The reason for using <CODE>_exit</CODE>
instead of <CODE>exit</CODE> is to avoid flushing fully buffered streams such
as <CODE>stdout</CODE>.  The buffers of these streams probably contain data
that was copied from the parent process by the <CODE>fork</CODE>, data that
will be output eventually by the parent process.  Calling <CODE>exit</CODE> in
the child would output the data twice.  See section <A HREF="library_22.html#SEC400" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC400">Termination Internals</A>.
<P>Go to the <A HREF="library_22.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html">previous</A>, <A HREF="library_24.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html">next</A> section.<P>