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

December 20, 2022 | Debian