wait4()
Wait for one or more child process to change its state
Synopsis:
#include <sys/resource.h>
#include <sys/wait.h>
pid_t wait4( pid_t pid,
int * stat_loc,
int options,
struct rusage * resource_usage );
Arguments:
- pid
- The set of child processes that you want to get status information for:
- less than -1 — any child process whose process group ID is equal to the absolute value of pid
- -1 — any child process
- 0 — any child process whose process group ID is equal to that of the calling process
- greater than 0 — the single child process with this ID
- stat_loc
- NULL, or a pointer a location where the function can
store the terminating status of the child process.
For information about macros that extract information from this status, see
Status macros
in the documentation for wait(). - options
- A combination of zero or more of the following flags:
- WCONTINUED — return the status for any child that was stopped and has been continued.
- WNOHANG — return immediately if there are no children to wait for.
- WNOWAIT — keep the process in a waitable state. This doesn't affect the state of the process; the process may be waited for again after this call completion.
- WSTOPPED — wait for and return the process status of any child that has stopped because it received a signal.
- WUNTRACED — report the status of a stopped child process. In QNX OS, this is the same as WSTOPPED.
- resource_usage
- NULL, or a pointer to an rusage structure where the function can store information about resource usage. For information about this structure, see getrusage().
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The wait4() function suspends execution of the calling thread until status information from one of its terminated child processes is available, or until the delivery of a signal whose action is either to terminate the process or execute a signal handler. If status information is available prior to the call to wait4(), the return is immediate.
- In order to wait for the status of a terminated child process whose real or saved user ID is different from the calling process's real or effective user ID, your process must have the PROCMGR_AID_WAIT ability enabled. For more information, see procmgr_ability().
- If the parent process sets the action for SIGCHLD to SIG_IGN, its children won't enter the zombie state, and it won't be able to use the wait*() functions to wait on their deaths.
The wait4() function behaves the same as the wait() function when passed a pid argument of -1 and an options argument with a value of zero (0).
Only one of the WIFEXITED(stat_val) and WIFSIGNALED(stat_val) macros can evaluate to a nonzero value.
wait3( stat_loc, options, resource_usage );
waitpid( (pid_t)-1, stat_loc, options );
wait4( (pid_t)-1, stat_loc, options, resource_usage );
The waitpid() function is POSIX; wait3() and wait4() are BSD extensions.
Returns:
If the status of a child process is available and the function call succeeds, a value equal to the process ID of the child process for which status is reported.
- WNOHANG was set in options
- the calling process has at least one child process specified by pid
- status is not available for any process specified by pid
If an error occurred, -1 (errno is set).
Errors:
- ECHILD
- The calling process has no existing unwaited-for child processes that meet the criteria set by pid.
- EINTR
- The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.
- EINVAL
- The value of the options argument is invalid.
Classification:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |