| <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: <a rel="next" accesskey="n" href="Process-Completion-Status.html#Process-Completion-Status">Process Completion Status</a>, |
| Previous: <a rel="previous" accesskey="p" href="Executing-a-File.html#Executing-a-File">Executing a File</a>, |
| Up: <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"> |
| — 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 − <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 ‘<samp><span class="samp">|</span></samp>’ 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"> |
| — 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 (&status) |
| </pre> |
| <p class="noindent">is exactly equivalent to: |
| |
| <pre class="smallexample"> waitpid (-1, &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"> |
| — 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, &status, WNOHANG); |
| if (pid < 0) |
| { |
| perror ("waitpid"); |
| break; |
| } |
| if (pid == 0) |
| break; |
| notice_termination (pid, status); |
| } |
| errno = serrno; |
| } |
| </pre> |
| </body></html> |
| |
