.\"	$NetBSD: siginfo.2,v 1.24 2020/06/08 17:19:44 sevan Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Christos Zoulas.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd May 25, 2019
.Dt SIGINFO 2
.Os
.Sh NAME
.Nm siginfo
.Nd signal information
.Sh SYNOPSIS
.In signal.h
.Sh DESCRIPTION
.Nm
is a structure type which contains information about a signal delivered
to a process.
.Pp
.Nm
includes the following members:
.Bd -literal -offset indent
int si_signo;
int si_errno;
int si_code;
.Ed
.Pp
.Fa si_signo
contains the signal number generated by the system.
.Pp
If
.Fa si_errno
is non-zero, then it contains a system specific error number associated
with this signal.
This number is defined in
.Xr errno 2 .
.Pp
If
.Fa si_code
is less than or equal to zero, the signal was generated by a user process
or a user requested service:
.Bl -tag -width SI_ASYNCIO
.It SI_USER
The signal was generated via
.Xr kill 2 .
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the sending process and the
.Fa si_uid
field contains the user id of the sending process.
.It SI_QUEUE
The signal was generated via
.Xr sigqueue 2 .
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
sigval_t si_value;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the sending process and the
.Fa si_uid
field contains the user id of the sending process.
Finally, the
.Fa si_value
field contains the value sent via
.Xr sigqueue 2 .
.It SI_TIMER
The signal was generated because a timer set by
.Xr timer_settime 2
has expired.
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
sigval_t si_value;
.Ed
.Pp
The
.Fa si_value
field contains the value set via
.Xr timer_create 2 .
.It SI_ASYNCIO
The signal was generated by completion of an asynchronous I/O operation.
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
int si_fd;
long si_band;
.Ed
.Pp
The
.Fa si_fd
argument contains the file descriptor number on which the operation was
completed and the
.Fa si_band
field contains the side and priority of the operation.
If the operation was a normal read,
.Fa si_band
will contain
.Dv POLLIN | POLLRDNORM ;
on an out-of-band read it will contain
.Dv POLLPRI | POLLRDBAND ;
on a normal write it will contain
.Dv POLLOUT | POLLWRNORM ;
on an out-of-band write it will contain
.Dv POLLPRI | POLLWRBAND .
.It SI_MESGQ
The signal was generated because of the arrival of a message on an empty
message queue.
See
.Xr mq_notify 3 .
.It SI_LWP
The signal was generated via
.Xr _lwp_kill 2 .
The
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the sending process and the
.Fa si_uid
field contains the user id of the sending process.
.It SI_NOINFO
The signal was generated without specific info available.
.El
.Pp
If
.Fa si_code
is positive, then it contains a signal specific reason
why the signal was generated:
.Bl -tag -width SIGCHLD
.It SIGILL
.Bl -tag -width ILL_ILLOPC
.It ILL_BADSTK
Internal stack error
.It ILL_COPROC
Coprocessor error
.It ILL_ILLADR
Illegal addressing mode
.It ILL_ILLOPC
Illegal opcode
.It ILL_ILLOPN
Illegal operand
.It ILL_ILLTRP
Illegal trap
.It ILL_PRVOPC
Privileged opcode
.It ILL_PRVREG
Privileged register
.El
.It SIGFPE
.Bl -tag -width FPE_INTDIV
.It FPE_FLTDIV
Floating-point divide by zero
.It FPE_FLTINV
Invalid floating-point operation
.It FPE_FLTOVF
Floating-point overflow
.It FPE_FLTRES
Floating-point inexact result
.It FPE_FLTUND
Floating-point underflow
.It FPE_FLTSUB
Subscript out of range
.It FPE_INTDIV
Integer divide by zero
.It FPE_INTOVF
Integer overflow
.El
.It SIGSEGV
.Bl -tag -width SEGV_MAPERR
.It SEGV_ACCERR
Invalid permissions for mapped object
.It SEGV_MAPERR
Address not mapped to object
.El
.It SIGBUS
.Bl -tag -width BUS_ADRALN
.It BUS_ADRALN
Invalid address alignment
.It BUS_ADRERR
Nonexistent physical address
.It BUS_OBJERR
Object-specific hardware error
.El
.It SIGTRAP
.Bl -tag -width TRAP_BRKPT
.It TRAP_BRKPT
Process breakpoint
.It TRAP_CHLD
Process child trap
.It TRAP_DBREG
Process hardware debug register trap
.It TRAP_EXEC
Process exec trap
.It TRAP_LWP
Process LWP trap
.It TRAP_SCE
Process syscall entry trap
.It TRAP_SCX
Process syscall exit trap
.It TRAP_TRACE
Process trace trap
.El
.It SIGCHLD
.Bl -tag -width CLD_CONTINUED
.It CLD_CONTINUED
Stopped child has continued
.It CLD_DUMPED
Child has terminated abnormally and created a core file
.It CLD_EXITED
Child has exited
.It CLD_KILLED
Child has terminated abnormally but did not create a core file
.It CLD_STOPPED
Child has stopped
.It CLD_TRAPPED
Traced child has trapped
.El
.It SIGIO
.Bl -tag -width POLL_OUT
.It POLL_ERR
I/O error
.It POLL_HUP
Device disconnected
.It POLL_IN
Data input available
.It POLL_MSG
Input message available
.It POLL_OUT
Output buffers available
.It POLL_PRI
High priority input available
.El
.El
.Pp
For
.Dv SIGILL ,
.Dv SIGFPE ,
.Dv SIGBUS
and
.Dv SIGSEGV
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
void *si_addr;
int si_trap;
.Ed
.Pp
.Fa si_addr
contains the address of the faulting instruction or data and
.Fa si_trap
contains a hardware specific reason.
.Pp
For
.Dv SIGTRAP
and
.Dv TRAP_BRKPT ,
.Dv TRAP_TRACE
or
.Dv TRAP_DBREG
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
void *si_addr;
int si_trap;
.Ed
.Pp
.Fa si_addr
contains the address of the faulting data and
.Fa si_trap
contains a hardware specific reason.
.Pp
For
.Dv SIGTRAP
and
.Dv TRAP_SCE
or
.Dv TRAP_SCX
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
int si_sysnum;
int si_retval[2];
int si_error;
uint64_t si_args[8];
.Ed
.Pp
.Fa si_sysnum
contains the syscall number,
.Fa si_retval
contains the syscall return value (meaningful for
.Dv TRAP_SCX
only),
.Fa si_error
contains the syscall error value (meaningful for
.Dv TRAP_SCX
only) and
.Fa si_args[8]
contains the syscall arguments,
.Pp
For
.Dv SIGIO
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
int si_fd;
long si_band;
.Ed
.Pp
The
.Fa si_fd
argument contains the file descriptor number on which the operation was
completed and the
.Fa si_band
field contains the side and priority of the operation as described above.
.Pp
Finally, for
.Dv SIGCHLD
the
.Nm
structure contains the following additional members:
.Bd -literal -offset indent
pid_t si_pid;
uid_t si_uid;
int si_status;
clock_t	si_utime;
clock_t	si_stime;
.Ed
.Pp
The
.Fa si_pid
field contains the pid of the process who's status changed, the
.Fa si_uid
field contains the user id of the that process, the
.Fa si_status
field contains either the exit code of the process (for
.Dv CLD_EXITED ) ,
or the signal number received by the process.
.Xr waitid 2 ,
.Xr waitpid 2 ,
and the
.Fa si_utime
and
.Fa si_stime
fields contain the user and system process accounting time.
.Sh STANDARDS
The
.Nm
type conforms to
.St -xsh5 .
.Pp
Signals specifying
.Dv SI_LWP
or
.Dv SI_NOINFO
are
.Nx
extensions.
.Pp
The
.Dv TRAP_CHLD ,
.Dv TRAP_DBREG ,
.Dv TRAP_EXEC ,
.Dv TRAP_LWP ,
.Dv TRAP_SCE
and
.Dv TRAP_SCX
signal specific reasons of
.Dv SIGTRAP
are
.Nx
extensions.
.Sh HISTORY
The
.Nm
functionality first appeared in
.At V.4 .
.Pp
.Dv TRAP_CHLD ,
.Dv TRAP_DBREG ,
.Dv TRAP_EXEC ,
.Dv TRAP_LWP ,
.Dv TRAP_SCE
and
.Dv TRAP_SCX
first appeared
in
.Nx 8 .
.Pp
The additional parameters with syscall information in
.Dv TRAP_SCE
and
.Dv TRAP_SCX
first appeared in
.Nx 9 .