OpenBSD manual page server

Manual Page Search Parameters
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.

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-current