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.
- EPERM
- The calling process doesn't have the required permission; see procmgr_ability() .
Classification:
Safety: | |
---|---|
Cancellation point | Yes |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |