wait()

Wait for the status of a terminated child process

Synopsis:

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

pid_t wait( int * stat_loc );

Arguments:

stat_loc: NULL, or a pointer to a location where the function can store the terminating status of the child. For more information, see “Status macros,” below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The wait() 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 wait(), the return is immediate.

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()).

Status macros

If the stat_loc variable is non-NULL, the terminating status of the child process is in the location that it points to. The macros listed below, defined in <sys/wait.h>, extract information from stat_loc. The stat_val argument to these macros is the integer value pointed to by stat_loc.

POSIX defines the following macros:

WEXITSTATUS( stat_val ): Evaluates to the low-order 8 bits of the termination status of the child process if the value of WIFEXITED( stat_val ) is nonzero.
WIFCONTINUED( stat_val ): Evaluates to a nonzero value if the status returned was from a child process that has continued from a job control stop.
WIFEXITED( stat_val ): Evaluates to a nonzero value if the status returned was from a normally terminated child process.
WIFSIGNALED( stat_val ): Evaluates to nonzero value if the child process terminated from reception of a signal that wasn't caught.
WIFSTOPPED( stat_val ): Evaluates to a nonzero value if the status returned is for a child process that's stopped.
WSTOPSIG( stat_val ): Evaluates to the number of the signal that caused the child process to stop if the value of WIFSTOPPED( stat_val ) is nonzero.
WTERMSIG( stat_val ): Evaluates to the number of the signal that terminated the child process if the value of WIFSIGNALED( stat_val ) is nonzero.

This macro isn't part of a POSIX standard:

WCOREDUMP( stat_val ): Evaluates to a nonzero value if the child process left a core dump.

One of the macros WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) evaluates to a nonzero value.

The non-POSIX waitid() function gives even more status information than the above macros.

Returns:

The process ID of the terminating child process, or -1 if an error occurred or on delivery of a signal (errno is set to EINTR).

Errors:

ECHILD: The calling process has no existing unwaited-for child processes.
EINTR: The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.
EPERM: The calling process doesn't have the required permission; see procmgr_ability().

Classification:

POSIX 1003.1

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