wait3()

Updated: April 19, 2023

Wait for any child process to change its state

Synopsis:

#include <sys/resource.h>
#include <sys/wait.h>

pid_t wait3( int * stat_loc,
             int options,
             struct rusage * resource_usage );

Arguments:

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 Neutrino, this is the same as WSTOPPED.
resource_usage
NULL, or a pointer to a 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 wait3() function allows the calling thread to obtain status information for specified child processes.

Note:
  • 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.
  • If the calling process is a guardian, it may wait on processes that are not its children (see procmgr_guardian()).

The following call:

wait3( stat_loc, options, resource_usage );

is equivalent to:

waitpid( (pid_t)-1, stat_loc, options );

except that on successful completion, if the resource_usage argument to wait3() isn't a null pointer, the rusage structure that the third argument points to is filled in for the child process identified by the return value.

It's also equivalent to:

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, a value equal to the process ID of the child process for which status is reported.

If a signal is delivered to the calling process, -1 and errno is set to EINTR.

Zero if wait3() is invoked with WNOHANG set in options and at least one child process is specified by pid for which status isn't available, and status isn't available for any process specified by pid.

Otherwise, (pid_t)-1 and errno is set.

Errors:

ECHILD
The calling process has no existing unwaited-for child processes, or the set of processes specified by the argument pid can never be in the states specified by the argument options.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Classification:

Unix

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes