waitid() — Wait for child process to change state

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/wait.h>

int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);

General description

The waitid() function suspends the calling process until one of its children changes state. It records the current state of a child in the structure pointed to by infop. If a child process changed state before the call, waitid() returns immediately.

The idtype and id arguments are used to specify which children waitid() will wait for.

If idtype is P_PID waitid() will wait for the child with a process ID equal to (pid_t)id.

If idtype is P_GID waitid() will wait for any child with a process group ID equal to (pid_t)id.

If idtype is P_ALL waitid() will wait for any children and id is ignored.

The options argument is used to specify which state changes to wait for. It is formed by OR-ing together one or more of the following flags:
WCONTINUED
Status will be returned for any child that has stopped and has been continued.
WEXITED
Wait for processes that have exited.
WNOHANG
Return immediately if there are no children to wait for.
WNOWAIT
Keep the process whose status is returned in infop in a waitable state. This will not affect the state of the process; the process may be waited for again after this call completes.
WSTOPPED
Status will be returned for any child that has stopped upon receipt of a signal.

The infop argument must point to a siginfo_t structure. If waitid() returns because a child process was found that specified the conditions indicated by the arguments idtype and options then the structure pointed to by infop will be filled in by the system with the status of the process. The si_signo member will always be equal to SIGCHLD.

Returned value

If waitid() returns due to the change of state of one of its children, it returns 0.

If unsuccessful, waitid() returns -1 and sets errno to one of the following values:
Error Code
Description
ECHILD
The calling process has no existing unwaited-for child processes.
EINTR
The waitid() function was interrupted due to the receipt of a signal by the calling process.
EINVAL
An invalid value was specified for options, or idtype and id specify an invalid set of processes.

Related information

Parent topic: Library functions