WAITID(2) System Calls Manual WAITID(2)

waitid — wait for process state change

#include <sys/wait.h>

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

The () 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, () 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:

Causes status to be reported for selected child processes that were previously stopped and which have been continued by receipt of a SIGCONT signal.
Reports the status of selected processes which have terminated.
Indicates that the call should not block if there are no selected processes that have a status change to report.
Keeps the process whose status is returned in a waitable state. The process may be waited for again after this call completes.
Reports the status of selected processes which are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal.
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 () 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:

The process was previously stopped and was continued. si_status will be set to SIGCONT. Only returned if options includes WCONTINUED.
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.
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.
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.
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.
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 () didn't find a matching process, si_signo and si_pid will be set to zero.

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.

waitid() will fail and return immediately if:

[]
The calling process has no existing unwaited-for child processes.
[]
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.
[]
The infop argument points to an illegal address. (May not be detected before exit of a child process.)
[]
The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set.
[]
Invalid or undefined flags were passed in the options argument, or idtype and id specified an invalid set of processes.

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

The waitid() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”). The WTRAPPED macro is an extension to that specification.

December 20, 2022 OpenBSD 7.5