|HP-UX Reference > W
HP-UX 11i Version 3: February 2007
wait(), waitpid() — wait for child process to stop or terminate
#include <sys/types.h> #include <sys/wait.h> pid_t wait( int *stat_loc ); pid_t waitpid( pid_t pid, int *stat_loc, int options );
The wait() and waitpid() functions obtain status information pertaining to one of the caller's child processes. Various options permit status information to be obtained for child processes that have terminated or stopped. If status information is available for two or more child processes, the order in which their status is reported is unspecified.
The wait() function suspends execution of the calling thread until status information for one of the terminated child processes of the calling process is available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. If more than one thread is suspended in wait() or waitpid() awaiting termination of the same process, exactly one thread returns the process status at the time of the target process termination. If status information is available prior to the call to wait(), return is immediate.
The waitpid() function is equivalent to wait() if the pid argument is (pid_t)-1 and the options argument is 0. Otherwise, its behavior is modified by the values of the pid and options arguments.
Note that if the parent process terminates without waiting for its child processes to terminate, these processes are adopted by and recognize the initialization process as their parent.
The pid argument specifies the child processes for which status is requested. The waitpid() function only returns the status of a child process from this set:
The stat_loc argument is the address where status of the specified child processes is placed.
The options argument is constructed from the bitwise-inclusive OR of zero or more of the following flags defined in the <sys/wait.h> header file.
If the calling process has the signal action SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN, and the process has no unwaited-for children that were transformed into zombie processes, the calling thread blocks until all of the children of the process containing the calling thread terminate, and wait() and waitpid() fail and set errno to ECHILD.
If wait() or waitpid() return because the status of a child process is available, these functions return a value equal to the process ID of the child process. In this case, if the value of the argument stat_loc is not a null pointer, information is stored in the location pointed to by stat_loc. The value stored at the location pointed to by stat_loc is 0 if and only if the status returned is from a terminated child process that terminated by one of the following means:
Previous versions of HP-UX documented the bit encodings of the status returned by wait() which could be interpreted directly and applications doing this will continue to work correctly. However, new applications should use the provided status interpretation macros shown below for maximum portability.
Status Interpretation Macros
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; the stat_val argument is the integer value pointed to by stat_loc.
If the information pointed to by stat_loc was stored by a call to waitpid() 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) evaluates to a nonzero value.
If the information pointed to by stat_loc was stored by a call to waitpid() that specified the WUNTRACED and WCONTINUED flags, exactly one of the macros WIFCONTINUED(*stat_loc), WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and WIFSTOPPED(*stat_loc) evaluates to a nonzero value.
If the information pointed to by stat_loc was stored by a call to waitpid() that did not specify the WUNTRACED or WCONTINUED flags, or by a call to the wait() function, exactly one of the macros WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) evaluates to a nonzero value.
If the information pointed to by stat_loc was stored by a call to waitpid() that did not specify the WUNTRACED flag and specified the WCONTINUED lag, or by a call to the wait() function, exactly one of the macros WIFCONTINUED(*stat_loc), WIFEXITED(*stat_loc), and WIFSIGNALED(*stat_loc) evaluates to a nonzero value.
There may be additional implementation-dependent circumstances under which wait() and waitpid() report status. This does not occur unless the calling process or one of its child processes explicitly makes use of a nonstandard extension. In these cases the interpretation of the reported status is implementation-defined.
If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned a new parent process ID corresponding to an implementation-defined system process.
In earlier versions of HP-UX, the status interpretation macros WIFEXITED, WIFSIGNALED, and WIFSTOPPED have the same definitions as the correspondingly named macros in BSD 4.3 and earlier systems, so existing applications that depend on these definitions will continue to work correctly. However, if the application is recompiled, the feature test macro _BSD must be turned on so that the old definitions of these macros override the new definitions of these macros that are in effect by default. The only difference between the old and new definitions is the argument typing. Type union wait is used in the BSD definitions while type int is used in the default definitions.
If wait() or waitpid() returns because the status of a child process is available, these functions return a value equal to the process ID of the child process for which status is reported.
If wait() or waitpid() returns due to the delivery of a signal to the calling process, -1 is returned and errno is set to EINTR.
If waitpid() was invoked with WNOHANG set in options, it has at least one child process specified by pid for which status is not available, and status is not available for any process specified by pid, 0 is returned. Otherwise, (pid_t)-1 is returned, and errno is set to indicate the error.
If the wait() call fails, errno is set to one of the following values:
If the waitpid() call fails, errno is set to one of the following values:
HP-UX EXTENSION: The operation of wait(), waitpid() is affected if the SIGCLD signal is set to SIG_IGN (see the WARNINGS section of signal(5)). Signal handlers that cause system calls to be restarted can affect the EINTR condition (see bsdproc(3C) and sigaction(2)).
In a multithreaded application, only the calling thread is suspended by wait(), waitpid() call.
wait() and waitpid() will not return until all threads in the process have reached the desired state. For example, the wait(), waitpid() calls will not return until all threads have terminated. If the WUNTRACED or WCONTINUED options are specified for the waitpid() call, it will not return until all threads have stopped or continued, respectively.
wait(), waitpid(), and wait3() were developed by HP, AT&T and the University of California, Berkeley.