1.\" $OpenBSD: waitid.2,v 1.2 2022/12/20 09:01:05 jmc Exp $ 2.\" $NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)wait.2 8.2 (Berkeley) 4/19/94 32.\" 33.Dd $Mdocdate: December 20 2022 $ 34.Dt WAITID 2 35.Os 36.Sh NAME 37.Nm waitid 38.Nd wait for process state change 39.Sh SYNOPSIS 40.In sys/wait.h 41.Ft int 42.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *infop" "int options" 43.Sh DESCRIPTION 44The 45.Fn waitid 46function suspends execution of its calling process until 47a selected state change occurs for a matching child process, 48or a signal is received. 49.Pp 50The set of child processes to be queried is specified by the arguments 51.Fa idtype 52and 53.Fa id . 54.Bl -dash -offset indent 55.It 56If 57.Fa idtype 58is 59.Dv P_PID , 60.Fn waitid 61waits for the child process with a process ID equal to 62.Dv (pid_t)id . 63.It 64If 65.Fa idtype 66is 67.Dv P_PGID , 68.Fn waitid 69waits for the child process with a process group ID equal to 70.Dv (pid_t)id . 71.It 72If 73.Fa idtype 74is 75.Dv P_ALL , 76.Fn waitid 77waits for any child process and the 78.Dv id 79is ignored. 80.El 81.Pp 82The 83.Fa options 84argument is the bitwise OR of zero or more of the following values: 85.Bl -tag -width "WCONTINUED" 86.It Dv WCONTINUED 87Causes status to be reported for selected child processes that were 88previously stopped and which have been continued by receipt of a 89.Dv SIGCONT 90signal. 91.It Dv WEXITED 92Reports the status of selected processes which have terminated. 93.It Dv WNOHANG 94Indicates that the call should not block if there are no selected processes 95that have a status change to report. 96.It Dv WNOWAIT 97Keeps the process whose status is returned in a waitable state. 98The process may be waited for again after this call completes. 99.It Dv WSTOPPED 100Reports the status of selected processes which are stopped due to a 101.Dv SIGTTIN , SIGTTOU , SIGTSTP , 102or 103.Dv SIGSTOP 104signal. 105.It Dv WTRAPPED 106Reports the status of selected processes which are stopped due to a 107process tracing event 108.Xr ( ptrace 2 ) . 109.El 110.Pp 111At least one of 112.Dv WCONTINUED , WEXITED , WSTOPPED , 113or 114.Dv WTRAPPED 115must be specified. 116.Pp 117If 118.Fn waitid 119found a matching process, the structure referenced by 120.Fa infop 121is filled with the status of the process: 122.Fa si_signo 123is set to 124.Dv SIGCHLD , 125and 126.Fa si_pid 127and 128.Fa si_uid 129are set to the process ID and effective user ID of the matched process. 130.Fa si_code 131will be set to one of the following values: 132.Bl -tag -width "CLD_CONTINUED" 133.It Dv CLD_CONTINUED 134The process was previously stopped and was continued. 135.Fa si_status 136will be set to 137.Dv SIGCONT . 138Only returned if 139.Fa options 140includes 141.Dv WCONTINUED . 142.It Dv CLD_DUMPED 143The process was killed by a signal and a core file was generated. 144.Fa si_status 145will be set to the signal that killed the process. 146Only returned if 147.Fa options 148includes 149.Dv WEXITED . 150.It Dv CLD_EXITED 151The process exited normally. 152.Fa si_status 153will be set to the full 154.Ft int 155value that was passed to 156.Xr _exit 2 . 157Only returned if 158.Fa options 159includes 160.Dv WEXITED . 161.It Dv CLD_KILLED 162The process was killed by a signal with generation of a core file. 163.Fa si_status 164will be set to the signal that killed the process. 165Only returned if 166.Fa options 167includes 168.Dv WEXITED . 169.It Dv CLD_STOPPED 170The process was stopped due to a signal. 171.Fa si_status 172will be set to the signal that stopped the process. 173Only returned if 174.Fa options 175includes 176.Dv WSTOPPED . 177.It Dv CLD_TRAPPED 178The process was stopped due to process tracing 179.Xr ( ptrace 2 ) . 180.Fa si_status 181will be set to the signal that caused the trap. 182Only returned if 183.Fa options 184includes 185.Dv WTRAPPED . 186.El 187.Pp 188If 189.Dv WNOHANG 190was specified and 191.Fn waitid 192didn't find a matching process, 193.Fa si_signo 194and 195.Fa si_pid 196will be set to zero. 197.Sh RETURN VALUES 198If 199.Fn waitid 200returns because one or more processes have a state change to report, 2010 is returned. 202If an error is detected, 203a value of -1 204is returned and 205.Va errno 206is set to indicate the error. 207If 208.Dv WNOHANG 209is specified and there are 210no stopped, continued or exited children, 2110 is returned. 212.Sh ERRORS 213.Fn waitid 214will fail and return immediately if: 215.Bl -tag -width Er 216.It Bq Er ECHILD 217The calling process has no existing unwaited-for child processes. 218.It Bq Er ECHILD 219No status from the terminated child process is available 220because the calling process has asked the system to discard 221such status by ignoring the signal 222.Dv SIGCHLD 223or setting the flag 224.Dv SA_NOCLDWAIT 225for that signal. 226.It Bq Er EFAULT 227The 228.Fa infop 229argument points to an illegal address. 230(May not be detected before exit of a child process.) 231.It Bq Er EINTR 232The call was interrupted by a caught signal, or the signal did not have the 233.Dv SA_RESTART 234flag set. 235.It Bq Er EINVAL 236Invalid or undefined flags were passed in the 237.Fa options 238argument, or 239.Fa idtype 240and 241.Fa id 242specified an invalid set of processes. 243.El 244.Sh SEE ALSO 245.Xr _exit 2 , 246.Xr ptrace 2 , 247.Xr sigaction 2 , 248.Xr wait 2 , 249.Xr exit 3 250.Sh STANDARDS 251The 252.Fn waitid 253function conforms to 254.St -p1003.1-2008 . 255The 256.Dv WTRAPPED 257macro is an extension to that specification. 258.\" .Sh HISTORY 259.\" A 260.\" .Fn waitid 261.\" system call first appeared in 262