WAITID(2)

NAME
waitid - wait for process state change

SYNOPSIS
#include <sys/wait.h>
int
waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);

DESCRIPTION
The waitid() function suspends execution of its calling process until a selected state change occurs for a matching child process, or a signal is received.

The set of child processes to be queried is specified by the arguments idtype and id.

-   If idtype is P_PID, waitid() waits for the child process with a process ID equal to (pid_t)id.

-   If idtype is P_PGID, waitid() waits for the child process with a process group ID equal to (pid_t)id.

-   If idtype is P_ALL, waitid() waits for any child process and the id is ignored.

The options argument is the bitwise OR of zero or more of the following values:

WCONTINUED
    Causes status to be reported for selected child processes that were previously stopped and which have been continued by receipt of a SIGCONT signal.

WEXITED
    Reports the status of selected processes which have terminated.

WNOHANG
    Indicates that the call should not block if there are no selected processes that have a status change to report.

WNOWAIT
    Keeps the process whose status is returned in a waitable state. The process may be waited for again after this call completes.

WSTOPPED
    Reports the status of selected processes which are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal.

WTRAPPED
    Reports the status of selected processes which are stopped due to a process tracing event ((ptrace) 2).

At least one of WCONTINUED, WEXITED, WSTOPPED, or WTRAPPED must be specified.

If waitid() found a matching process, the structure referenced by infop is filled with the status of the process: si_signo is set to SIGCHLD, and si_pid and si_uid are set to the process ID and effective user ID of the matched process. si_code will be set to one of the following values:

CLD_CONTINUED
    The process was previously stopped and was continued. si_status will be set to SIGCONT. Only returned if options includes WCONTINUED.

CLD_DUMPED
    The process was killed by a signal and a core file was generated. si_status will be set to the signal that killed the process. Only returned if options includes WEXITED.

CLD_EXITED
    The process exited normally. si_status will be set to the full int value that was passed to _exit(2). Only returned if options includes WEXITED.

CLD_KILLED
    The process was killed by a signal with generation of a core file. si_status will be set to the signal that killed the process. Only returned if options includes WEXITED.

CLD_STOPPED
    The process was stopped due to a signal. si_status will be set to the signal that stopped the process. Only returned if options includes WSTOPPED.

CLD_TRAPPED
    The process was stopped due to process tracing ((ptrace) 2). si_status will be set to the signal that caused the trap. Only returned if options includes WTRAPPED.

If WNOHANG was specified and waitid() didn't find a matching process, si_signo and si_pid will be set to zero.

RETURN VALUES
If waitid() returns because one or more processes have a state change to report, 0 is returned. If an error is detected, a value of -1 is returned and errno is set to indicate the error. If WNOHANG is specified and there are no stopped, continued or exited children, 0 is returned.

ERRORS
waitid() will fail and return immediately if:

[ECHILD]
    The calling process has no existing unwaited-for child processes.

[ECHILD]
    No status from the terminated child process is available because the calling process has asked the system to discard such status by ignoring the signal SIGCHLD or setting the flag SA_NOCLDWAIT for that signal.

[EFAULT]
    The infop argument points to an illegal address. (May not be detected before exit of a child process.)

[EINTR]
    The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set.

[EINVAL]
    Invalid or undefined flags were passed in the options argument, or idtype and id specified an invalid set of processes.

SEE ALSO
_exit(2), ptrace(2), sigaction(2), wait(2), exit(3)

STANDARDS
The waitid() function conforms to p1003.1-2008. The WTRAPPED macro is an extension to that specification.