waitid()

Wait for a child process to change state

Synopsis:

#include <sys/wait.h>

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

Library:

libc

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 prior to the call to waitid(), waitid() returns immediately.

The idtype indicates which children waitid() is to wait for:

P_PID

Wait for the child with a process ID of (pid_t)id.

P_PGID

Wait for any child with a process group ID equal to (pid_t)id.

P_ALL

Wait for any child -- id is ignored.

The options argument is used to specify which state changes waitid() is to wait for, and is any combination of:

WCONTINUED

Return the status for any child that was stopped and has been continued.

WEXITED

Wait for process(es) to exit.

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 status of stopped child process.

WTRAPPED

Wait for traced process(es) to become trapped or reach a breakpoint.

The infop argument must point to a siginfo_t structure, as defined in <sys/siginfo.h>. If waitid() returns because a child process was found that satisfied the conditions indicated by the arguments idtype and options, then the structure pointed to by infop is filled in by the system with the status of the process. The si_signo member is always SIGCHLD.

If idtype is P_ALL and options is WEXITED|WTRAPPED, waitid() is equivalent to wait().

Returns:

0

One of the children changed its state. If WNOHANG was used, 0 can be returned (indicating no error); however, no children may have changed state if info->si_pid is 0.

-1

An error occurred (errno is set).

Errors:

ECHILD

The set of processes specified by idtype and id doesn't contain any unwaited-for processes.

EFAULT

The infop argument points to an illegal address.

EINTR

The waitid() function was interrupted by a signal.

EINVAL

An invalid value was specified for options, or idtype and id specify an invalid set of processes.

Classification:

Unix

See also:

execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), exit(), fork(), pause(), sigaction(), signal(), wait(), wait3(), wait4(), waitpid()