Movatterモバイル変換

wait(3p) — Linux manual page

PROLOG \|NAME \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|EXAMPLES \|APPLICATION USAGE \|RATIONALE \|FUTURE DIRECTIONS \|SEE ALSO \|COPYRIGHT

WAIT(3P)                POSIX Programmer's ManualWAIT(3P)

PROLOG top

       This manual page is part of the POSIX Programmer's Manual.  The       Linux implementation of this interface may differ (consult the       corresponding Linux manual page for details of Linux behavior), or       the interface may not be implemented on Linux.

NAME top

       wait, waitpid — wait for a child process to stop or terminate

SYNOPSIS top

       #include <sys/wait.h>       pid_t wait(int *stat_loc);       pid_t waitpid(pid_tpid, int *stat_loc, intoptions);

DESCRIPTION top

       Thewait() andwaitpid() functions shall obtain status information       (seeSection 2.13,Status Information) pertaining to one of the       caller's child processes. Thewait() function obtains status       information for process termination from any child process. Thewaitpid() function obtains status information for process       termination, and optionally process stop and/or continue, from a       specified subset of the child processes.       Thewait() function shall cause the calling thread to become       blocked until status information generated by child process       termination is made available to the thread, or until delivery of       a signal whose action is either to execute a signal-catching       function or to terminate the process, or an error occurs. If       termination status information is available prior to the call towait(), return shall be immediate. If termination status       information is available for two or more child processes, the       order in which their status is reported is unspecified.       As described inSection 2.13,Status Information, thewait() andwaitpid() functions consume the status information they obtain.       The behavior when multiple threads are blocked inwait(),waitid(), orwaitpid() is described inSection 2.13,StatusInformation.       Thewaitpid() function shall be equivalent towait() if thepid       argument is (pid_t)-1 and theoptions argument is 0. Otherwise,       its behavior shall be modified by the values of thepid andoptions arguments.       Thepid argument specifies a set of child processes for whichstatus is requested. Thewaitpid() function shall only return the       status of a child process from this set:        *  Ifpid is equal to (pid_t)-1,status is requested for any           child process. In this respect,waitpid() is then equivalent           towait().        *  Ifpid is greater than 0, it specifies the process ID of a           single child process for whichstatus is requested.        *  Ifpid is 0,status is requested for any child process whose           process group ID is equal to that of the calling process.        *  Ifpid is less than (pid_t)-1,status is requested for any           child process whose process group ID is equal to the absolute           value ofpid.       Theoptions argument is constructed from the bitwise-inclusive OR       of zero or more of the following flags, defined in the<sys/wait.h> header:       WCONTINUED  Thewaitpid() function shall report the status of any                   continued child process specified bypid whose status                   has not been reported since it continued from a job                   control stop.       WNOHANG     Thewaitpid() function shall not suspend execution of                   the calling thread ifstatus is not immediately                   available for one of the child processes specified bypid.       WUNTRACED   The status of any child processes specified bypid                   that are stopped, and whose status has not yet been                   reported since they stopped, shall also be reported to                   the requesting process.       Ifwait() orwaitpid() return because the status of a child       process is available, these functions shall return a value equal       to the process ID of the child process. In this case, if the value       of the argumentstat_loc is not a null pointer, information shall       be stored in the location pointed to bystat_loc.  The value       stored at the location pointed to bystat_loc shall be 0 if and       only if the status returned is from a terminated child process       that terminated by one of the following means:        1. The process returned 0 frommain().        2. The process called_exit() orexit() with astatus argument of           0.        3. The process was terminated because the last thread in the           process terminated.       Regardless of its value, this information may be interpreted using       the following macros, which are defined in<sys/wait.h> and       evaluate to integral expressions; thestat_val argument is the       integer value pointed to bystat_loc.       WIFEXITED(stat_val)             Evaluates to a non-zero value ifstatus was returned for a             child process that terminated normally.       WEXITSTATUS(stat_val)             If the value of WIFEXITED(stat_val) is non-zero, this macro             evaluates to the low-order 8 bits of thestatus argument             that the child process passed to_exit() orexit(), or the             value the child process returned frommain().       WIFSIGNALED(stat_val)             Evaluates to a non-zero value ifstatus was returned for a             child process that terminated due to the receipt of a signal             that was not caught (see<signal.h>).       WTERMSIG(stat_val)             If the value of WIFSIGNALED(stat_val) is non-zero, this             macro evaluates to the number of the signal that caused the             termination of the child process.       WIFSTOPPED(stat_val)             Evaluates to a non-zero value ifstatus was returned for a             child process that is currently stopped.       WSTOPSIG(stat_val)             If the value of WIFSTOPPED(stat_val) is non-zero, this macro             evaluates to the number of the signal that caused the child             process to stop.       WIFCONTINUED(stat_val)             Evaluates to a non-zero value ifstatus was returned for a             child process that has continued from a job control stop.       It is unspecified whether thestatus value returned by calls towait() orwaitpid() for processes created byposix_spawn() orposix_spawnp() can indicate a WIFSTOPPED(stat_val) before       subsequent calls towait() orwaitpid() indicate       WIFEXITED(stat_val) as the result of an error detected before the       new process image starts executing.       It is unspecified whether thestatus value returned by calls towait() orwaitpid() for processes created byposix_spawn() orposix_spawnp() can indicate a WIFSIGNALED(stat_val) if a signal is       sent to the parent's process group afterposix_spawn() orposix_spawnp() is called.       If the information pointed to bystat_loc was stored by a call towaitpid() that specified the WUNTRACED flag and did not specify       the WCONTINUED flag, exactly one of the macros       WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and       WIFSTOPPED(*stat_loc) shall evaluate to a non-zero value.       If the information pointed to bystat_loc was stored by a call towaitpid() that specified the WUNTRACED and WCONTINUED flags,       exactly one of the macros WIFEXITED(*stat_loc),       WIFSIGNALED(*stat_loc), WIFSTOPPED(*stat_loc), and       WIFCONTINUED(*stat_loc) shall evaluate to a non-zero value.       If the information pointed to bystat_loc was stored by a call towaitpid() that did not specify the WUNTRACED or WCONTINUED flags,       or by a call to thewait() function, exactly one of the macros       WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to       a non-zero value.       If the information pointed to bystat_loc was stored by a call towaitpid() that did not specify the WUNTRACED flag and specified       the WCONTINUED flag, exactly one of the macros       WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and       WIFCONTINUED(*stat_loc) shall evaluate to a non-zero value.       If _POSIX_REALTIME_SIGNALS is defined, and the implementation       queues the SIGCHLD signal, then ifwait() orwaitpid() returns       because the status of a child process is available, any pending       SIGCHLD signal associated with the process ID of the child process       shall be discarded. Any other pending SIGCHLD signals shall remain       pending.       Otherwise, if SIGCHLD is blocked, ifwait() orwaitpid() return       because the status of a child process is available, any pending       SIGCHLD signal shall be cleared unless the status of another child       process is available.       For all other conditions, it is unspecified whether childstatus       will be available when a SIGCHLD signal is delivered.       There may be additional implementation-defined circumstances under       whichwait() orwaitpid() reportstatus.  This shall not occur       unless the calling process or one of its child processes       explicitly makes use of a non-standard extension. In these cases       the interpretation of the reportedstatus is implementation-       defined.       If a parent process terminates without waiting for all of its       child processes to terminate, the remaining child processes shall       be assigned a new parent process ID corresponding to an       implementation-defined system process.

RETURN VALUE top

       Ifwait() orwaitpid() returns because the status of a child       process is available, these functions shall return a value equal       to the process ID of the child process for whichstatus is       reported. Ifwait() orwaitpid() returns due to the delivery of a       signal to the calling process, -1 shall be returned anderrno set       to[EINTR].  Ifwaitpid() was invoked with WNOHANG set inoptions,       it has at least one child process specified bypid for whichstatus is not available, andstatus is not available for any       process specified bypid, 0 is returned. Otherwise, -1 shall be       returned, anderrno set to indicate the error.

ERRORS top

       Thewait() function shall fail if:ECHILDThe calling process has no existing unwaited-for child              processes.EINTRThe function was interrupted by a signal. The value of the              location pointed to bystat_loc is undefined.       Thewaitpid() function shall fail if:ECHILDThe process specified bypid does not exist or is not a              child of the calling process, or the process group              specified bypid does not exist or does not have any member              process that is a child of the calling process.EINTRThe function was interrupted by a signal. The value of the              location pointed to bystat_loc is undefined.EINVALTheoptions argument is not valid.The following sections are informative.

EXAMPLES top

Waiting for a Child Process and then Checking its Status       The following example demonstrates the use ofwaitpid(),fork(),       and the macros used to interpret the status value returned bywaitpid() (andwait()).  The code segment creates a child process       which does some unspecified work. Meanwhile the parent loops       performing calls towaitpid() to monitor the status of the child.       The loop terminates when child termination is detected.           #include <stdio.h>           #include <stdlib.h>           #include <unistd.h>           #include <sys/wait.h>           ...           pid_t child_pid, wpid;           int status;           child_pid = fork();           if (child_pid == -1) {      /* fork() failed */               perror("fork");               exit(EXIT_FAILURE);           }           if (child_pid == 0) {       /* This is the child */               /* Child does some work and then terminates */               ...           } else {                    /* This is the parent */               do {                   wpid = waitpid(child_pid, &status, WUNTRACED           #ifdef WCONTINUED       /* Not all implementations support this */                   | WCONTINUED           #endif                   );                   if (wpid == -1) {                       perror("waitpid");                       exit(EXIT_FAILURE);                   }                   if (WIFEXITED(status)) {                       printf("child exited, status=%d\n", WEXITSTATUS(status));                   } else if (WIFSIGNALED(status)) {                       printf("child killed (signal %d)\n", WTERMSIG(status));                   } else if (WIFSTOPPED(status)) {                       printf("child stopped (signal %d)\n", WSTOPSIG(status));           #ifdef WIFCONTINUED     /* Not all implementations support this */                   } else if (WIFCONTINUED(status)) {                       printf("child continued\n");           #endif                   } else {    /* Non-standard case -- may never happen */                       printf("Unexpected status (0x%x)\n", status);                   }               } while (!WIFEXITED(status) && !WIFSIGNALED(status));           }Waiting for a Child Process in a Signal Handler for SIGCHLD       The following example demonstrates how to usewaitpid() in a       signal handler for SIGCHLD without passing -1 as thepid argument.       (See the APPLICATION USAGE section below for the reasons why       passing apid of -1 is not recommended.) The method used here       relies on the standard behavior ofwaitpid() when SIGCHLD is       blocked. On historical non-conforming systems, the status of some       child processes might not be reported.           #include <stdlib.h>           #include <stdio.h>           #include <signal.h>           #include <sys/types.h>           #include <sys/wait.h>           #include <unistd.h>           #define CHILDREN 10           static void           handle_sigchld(int signum, siginfo_t *sinfo, void *unused)           {               int sav_errno = errno;               int status;               /*                * Obtain status information for the child which                * caused the SIGCHLD signal and write its exit code                * to stdout.               */               if (sinfo->si_code != CLD_EXITED)               {                   static char msg[] = "wrong si_code\n";                   write(2, msg, sizeof msg - 1);               }               else if (waitpid(sinfo->si_pid, &status, 0) == -1)               {                   static char msg[] = "waitpid() failed\n";                   write(2, msg, sizeof msg - 1);               }               else if (!WIFEXITED(status))               {                   static char msg[] = "WIFEXITED was false\n";                   write(2, msg, sizeof msg - 1);               }               else               {                   int code = WEXITSTATUS(status);                   char buf[2];                   buf[0] = '0' + code;                   buf[1] = '\n';                   write(1, buf, 2);               }               errno = sav_errno;           }           int           main(void)           {               int i;               pid_t pid;               struct sigaction sa;               sa.sa_flags = SA_SIGINFO;               sa.sa_sigaction = handle_sigchld;               sigemptyset(&sa.sa_mask);               if (sigaction(SIGCHLD, &sa, NULL) == -1)               {                   perror("sigaction");                   exit(EXIT_FAILURE);               }               for (i = 0; i < CHILDREN; i++)               {                   switch (pid = fork())                   {                   case -1:                       perror("fork");                       exit(EXIT_FAILURE);                   case 0:                       sleep(2);                       _exit(i);                   }               }               /* Wait for all the SIGCHLD signals, then terminate on SIGALRM */               alarm(3);               for (;;)                   pause();               return 0; /* NOTREACHED */           }

APPLICATION USAGE top

       Calls towait() will collect information about any child process.       This may result in interactions with other interfaces that may be       waiting for their own children (such as by use ofsystem()).  For       this and other reasons it is recommended that portable       applications not usewait(), but instead usewaitpid().  For these       same reasons, the use ofwaitpid() with apid argument of -1, and       the use ofwaitid() with theidtype argument set to P_ALL, are       also not recommended for portable applications.       As specified inConsequences of Process Termination, if the       calling process has SA_NOCLDWAIT set or has SIGCHLD set to       SIG_IGN, then the termination of a child process will not cause       status information to become available to a thread blocked inwait(),waitid(), orwaitpid().  Thus, a thread blocked in one of       the wait functions will remain blocked unless some other condition       causes the thread to resume execution (such as an[ECHILD]failure       due to no remaining children in the set of waited-for children).

RATIONALE top

       A call to thewait() orwaitpid() function only returnsstatus on       an immediate child process of the calling process; that is, a       child that was produced by a singlefork() call (perhaps followed       by anexec or other function calls) from the parent. If a child       produces grandchildren by further use offork(), none of those       grandchildren nor any of their descendants affect the behavior of       await() from the original parent process. Nothing in this volume       of POSIX.1‐2017 prevents an implementation from providing       extensions that permit a process to getstatus from a grandchild       or any other process, but a process that does not use such       extensions must be guaranteed to seestatus from only its direct       children.       Thewaitpid() function is provided for three reasons:        1. To support job control        2. To permit a non-blocking version of thewait() function        3. To permit a library routine, such assystem() orpclose(), to           wait for its children without interfering with other           terminated children for which the process has not waited       The first two of these facilities are based on thewait3()       function provided by 4.3 BSD. The function uses theoptions       argument, which is equivalent to an argument towait3().  The       WUNTRACED flag is used only in conjunction with job control on       systems supporting job control. Its name comes from 4.3 BSD and       refers to the fact that there are two types of stopped processes       in that implementation: processes being traced via theptrace()       debugging facility and (untraced) processes stopped by job control       signals. Sinceptrace() is not part of this volume of       POSIX.1‐2017, only the second type is relevant. The name WUNTRACED       was retained because its usage is the same, even though the name       is not intuitively meaningful in this context.       The third reason for thewaitpid() function is to permit       independent sections of a process to spawn and wait for children       without interfering with each other. For example, the following       problem occurs in developing a portable shell, or command       interpreter:           stream = popen("/bin/true");           (void) system("sleep 100");           (void) pclose(stream);       On all historical implementations, the finalpclose() fails to       reap thewait()status of thepopen().       The status values are retrieved by macros, rather than given as       specific bit encodings as they are in most historical       implementations (and thus expected by existing programs). This was       necessary to eliminate a limitation on the number of signals an       implementation can support that was inherent in the traditional       encodings. This volume of POSIX.1‐2017 does require that astatus       value of zero corresponds to a process calling_exit(0), as this       is the most common encoding expected by existing programs.  Some       of the macro names were adopted from 4.3 BSD.       These macros syntactically operate on an arbitrary integer value.       The behavior is undefined unless that value is one stored by a       successful call towait() orwaitpid() in the location pointed to       by thestat_loc argument. An early proposal attempted to make this       clearer by specifying each argument as *stat_loc rather thanstat_val.  However, that did not follow the conventions of other       specifications in this volume of POSIX.1‐2017 or traditional       usage. It also could have implied that the argument to the macro       must literally be *stat_loc; in fact, that value can be stored or       passed as an argument to other functions before being interpreted       by these macros.       The extension that affectswait() andwaitpid() and is common in       historical implementations is theptrace() function. It is called       by a child process and causes that child to stop and return astatus that appears identical to thestatus indicated by       WIFSTOPPED.  Thestatus ofptrace() children is traditionally       returned regardless of the WUNTRACED flag (or by thewait()       function). Most applications do not need to concern themselves       with such extensions because they have control over what       extensions they or their children use. However, applications, such       as command interpreters, that invoke arbitrary processes may see       this behavior when those arbitrary processes misuse such       extensions.       Implementations that supportcorefile creation or other       implementation-defined actions on termination of some processes       traditionally provide a bit in thestatus returned bywait() to       indicate that such actions have occurred.       Allowing thewait() family of functions to discard a pending       SIGCHLD signal that is associated with a successfully waited-for       child process puts them into thesigwait() andsigwaitinfo()       category with respect to SIGCHLD.       This definition allows implementations to treat a pending SIGCHLD       signal as accepted by the process inwait(), with the same meaning       of ``accepted'' as when that word is applied to thesigwait()       family of functions.       Allowing thewait() family of functions to behave this way permits       an implementation to be able to deal precisely with SIGCHLD       signals.       In particular, an implementation that does accept (discard) the       SIGCHLD signal can make the following guarantees regardless of the       queuing depth of signals in general (the list of waitable children       can hold the SIGCHLD queue):        1. If a SIGCHLD signal handler is established viasigaction()           without the SA_RESETHAND flag, SIGCHLD signals can be           accurately counted; that is, exactly one SIGCHLD signal will           be delivered to or accepted by the process for every child           process that terminates.        2. A singlewait() issued from a SIGCHLD signal handler can be           guaranteed to return immediately with status information for a           child process.        3. When SA_SIGINFO is requested, the SIGCHLD signal handler can           be guaranteed to receive a non-null pointer to asiginfo_t           structure that describes a child process for which a wait viawaitpid() orwaitid() will not block or fail.        4. Thesystem() function will not cause the SIGCHLD handler of a           process to be called as a result of thefork()/exec executed           withinsystem() becausesystem() will accept the SIGCHLD           signal when it performs awaitpid() for its child process.           This is a desirable behavior ofsystem() so that it can be           used in a library without causing side-effects to the           application linked with the library.       An implementation that does not permit thewait() family of       functions to accept (discard) a pending SIGCHLD signal associated       with a successfully waited-for child, cannot make the guarantees       described above for the following reasons:       Guarantee #1             Although it might be assumed that reliable queuing of all             SIGCHLD signals generated by the system can make this             guarantee, the counter-example is the case of a process that             blocks SIGCHLD and performs an indefinite loop offork()/wait() operations. If the implementation supports             queued signals, then eventually the system will run out of             memory for the queue. The guarantee cannot be made because             there must be some limit to the depth of queuing.       Guarantees #2 and #3             These cannot be guaranteed unless thewait() family of             functions accepts the SIGCHLD signal. Otherwise, afork()/wait() executed while SIGCHLD is blocked (as in thesystem() function) will result in an invocation of the             handler when SIGCHLD is unblocked, after the process has             disappeared.       Guarantee #4             Although possible to make this guarantee,system() would             have to set the SIGCHLD handler to SIG_DFL so that the             SIGCHLD signal generated by itsfork() would be discarded             (the SIGCHLD default action is to be ignored), then restore             it to its previous setting. This would have the undesirable             side-effect of discarding all SIGCHLD signals pending to the             process.

FUTURE DIRECTIONS top

       None.

COPYRIGHT top

       Portions of this text are reprinted and reproduced in electronic       form from IEEE Std 1003.1-2017, Standard for Information       Technology -- Portable Operating System Interface (POSIX), The       Open Group Base Specifications Issue 7, 2018 Edition, Copyright       (C) 2018 by the Institute of Electrical and Electronics Engineers,       Inc and The Open Group.  In the event of any discrepancy between       this version and the original IEEE and The Open Group Standard,       the original IEEE and The Open Group Standard is the referee       document. The original Standard can be obtained online athttp://www.opengroup.org/unix/online.html .       Any typographical or formatting errors that appear in this page       are most likely to have been introduced during the conversion of       the source files to man page format. To report such errors, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group                2017WAIT(3P)

Pages that refer to this page:signal.h(0p), sys_wait.h(0p), sh(1p), wait(1p), abort(3p), exit(3p), _Exit(3p), getrusage(3p), kill(3p), pclose(3p), popen(3p), posix_spawn(3p), pthread_join(3p), sigaction(3p), sighold(3p), system(3p), times(3p), waitid(3p), waitpid(3p)