--- /dev/null
+.\" $OpenBSD: waitid.2,v 1.1 2022/12/19 18:13:50 guenther Exp $
+.\" $NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd Exp $
+.\"
+.\" Copyright (c) 1980, 1991, 1993, 1994
+.\" The Regents of the University of California. All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" @(#)wait.2 8.2 (Berkeley) 4/19/94
+.\"
+.Dd $Mdocdate: December 19 2022 $
+.Dt WAITID 2
+.Os
+.Sh NAME
+.Nm waitid
+.Nd wait for process state change
+.Sh SYNOPSIS
+.In sys/wait.h
+.Ft int
+.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *infop" "int options"
+.Sh DESCRIPTION
+The
+.Fn waitid
+function suspends execution of its calling process until
+a selected state change occurs for a matching child process,
+or a signal is received.
+.Pp
+The set of child processes to be queried is specified by the arguments
+.Fa idtype
+and
+.Fa id .
+.Bl -bullet -offset indent
+.It
+If
+.Fa idtype
+is
+.Dv P_PID ,
+.Fn waitid
+waits for the child process with a process ID equal to
+.Dv (pid_t)id .
+.It
+If
+.Fa idtype
+is
+.Dv P_PGID ,
+.Fn waitid
+waits for the child process with a process group ID equal to
+.Dv (pid_t)id .
+.It
+If
+.Fa idtype
+is
+.Dv P_ALL ,
+.Fn waitid
+waits for any child process and the
+.Dv id
+is ignored.
+.El
+.Pp
+The
+.Fa options
+argument is the bitwise OR of zero or more of the following values:
+.Bl -tag -width "WCONTINUED"
+.It Dv WCONTINUED
+Causes status to be reported for selected child processes that were
+previously stopped and which have been continued by receipt of a
+.Dv SIGCONT
+signal.
+.It Dv WEXITED
+Report the status of selected processes which have terminated.
+.It Dv WNOHANG
+Indicates that the call should not block if there are no selected processes
+that have a status change to report.
+.It Dv WNOWAIT
+Keep the process whose status is returned in a waitable state.
+The process may be waited for again after this call completes.
+.It Dv WSTOPPED
+Report the status of selected processes which are stopped due to a
+.Dv SIGTTIN , SIGTTOU , SIGTSTP ,
+or
+.Dv SIGSTOP
+signal.
+.It Dv WTRAPPED
+Report the status of selected processes which are stopped due to a
+process tracing event
+.Xr ( ptrace 2 ) .
+.El
+.Pp
+At least one of
+.Dv WCONTINUED , WEXITED , WSTOPPED ,
+or
+.Dv WTRAPPED
+must be specified.
+.Pp
+If
+.Fn waitid
+found a matching process, the structure referenced by
+.Fa infop
+is filled with the status of the process:
+.Fa si_signo
+will be set to
+.Dv SIGCHLD ,
+.Fa si_pid
+and
+.Fa si_uid
+to the process ID and effective user ID of the matched process.
+.Fa si_code
+will be set to one of the following values:
+.Bl -tag -width "CLD_CONTINUED"
+.It Dv CLD_CONTINUED
+The process was previously stopped and was continued.
+.Fa si_status
+will be set to
+.Dv SIGCONT .
+Only returned if
+.Fa options
+includes
+.Dv WCONTINUED .
+.It Dv CLD_DUMPED
+The process was killed by a signal and a core file was generated.
+.Fa si_status
+will be set to the signal that killed the process.
+Only returned if
+.Fa options
+includes
+.Dv WEXITED .
+.It Dv CLD_EXITED
+The process exited normally.
+.Fa si_status
+will be set to the full
+.Ft int
+value that was passed to
+.Xr _exit 2 .
+Only returned if
+.Fa options
+includes
+.Dv WEXITED .
+.It Dv CLD_KILLED
+The process was killed by a signal with generation of a core file.
+.Fa si_status
+will be set to the signal that killed the process.
+Only returned if
+.Fa options
+includes
+.Dv WEXITED .
+.It Dv CLD_STOPPED
+The process was stopped due to a signal.
+.Fa si_status
+will be set to the signal that stopped the process.
+Only returned if
+.Fa options
+includes
+.Dv WSTOPPED .
+.It Dv CLD_TRAPPED
+The process was stopped due to process tracing
+.Xr ( ptrace 2 ) .
+.Fa si_status
+will be set to the signal that caused the trap.
+Only returned if
+.Fa options
+includes
+.Dv WTRAPPED .
+.El
+.Pp
+If
+.Dv WNOHANG
+was specified and
+.Fn waitid
+didn't find a matching process,
+.Fa si_signo
+and
+.Fa si_pid
+will be set to zero.
+.Sh NOTES
+See
+.Xr sigaction 2
+for a list of termination signals.
+A status of 0 indicates normal termination.
+.Pp
+If a parent process terminates without
+waiting for all of its child processes to terminate,
+the remaining child processes are assigned the parent
+process 1 ID (the init process ID).
+.Pp
+If a signal is caught while a
+.Fn waitid
+call is pending, the call may be interrupted or restarted when the
+signal-catching routine returns, depending on the options in effect
+for the signal; for further information, see
+.Xr siginterrupt 3 .
+.Sh RETURN VALUES
+If
+.Fn 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
+.Va errno
+is set to indicate the error.
+If
+.Dv WNOHANG
+is specified and there are
+no stopped, continued or exited children,
+0 is returned.
+.Sh ERRORS
+.Fn waitid
+will fail and return immediately if:
+.Bl -tag -width Er
+.It Bq Er ECHILD
+The calling process has no existing unwaited-for child processes.
+.It Bq Er 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
+.Dv SIGCHLD
+or setting the flag
+.Dv SA_NOCLDWAIT
+for that signal.
+.It Bq Er EFAULT
+The
+.Fa infop
+argument points to an illegal address.
+(May not be detected before exit of a child process.)
+.It Bq Er EINTR
+The call was interrupted by a caught signal, or the signal did not have the
+.Dv SA_RESTART
+flag set.
+.It Bq Er EINVAL
+Invalid or undefined flags were passed in the
+.Fa options
+argument, or
+.Fa idtype
+and
+.Fa id
+specified an invalid set of processes.
+.El
+.Sh SEE ALSO
+.Xr _exit 2 ,
+.Xr ptrace 2 ,
+.Xr sigaction 2 ,
+.Xr wait 2 ,
+.Xr exit 3
+.Sh STANDARDS
+The
+.Fn waitid
+function conforms to
+.St -p1003.1-2008 .
+The
+.Dv WTRAPPED
+macro is an extension to that specification.
+.\" .Sh HISTORY
+.\" A
+.\" .Fn waitid
+.\" system call first appeared in
projects / openbsd / commitdiff