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 IEEE Std 1003.1-2008 (“POSIX.1”). The WTRAPPED macro is an extension to that specification.