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.

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.

Classification:

POSIX 1003.1

See also:

errno, spawn(), wait4(), waitid(), waitpid()