'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SIGINFO.H 3HEAD "Feb 5, 2008"
.SH NAME
siginfo.h, siginfo \- signal generation information
.SH SYNOPSIS
.LP
.nf
#include <siginfo.h>
.fi

.SH DESCRIPTION
.sp
.LP
If a process is catching a signal,  it might request information that tells why
the system generated that signal. See  \fBsigaction\fR(2). If a process is
monitoring its children, it might receive information that tells why a child
changed state. See  \fBwaitid\fR(2). In either case, the system returns the
information in a structure of type  \fBsiginfo_t\fR, which includes the
following information:
.sp
.in +2
.nf
int            si_signo        /* signal number */
int            si_errno        /* error number */
int            si_code         /* signal code */
union sigval   si_value        /* signal value */
.fi
.in -2

.sp
.LP
\fBsi_signo\fR contains the system-generated signal number. For the
\fBwaitid\fR(2) function,  \fBsi_signo\fR is always  \fBSIGCHLD\fR.
.sp
.LP
If  \fBsi_errno\fR is non-zero, it contains an error number associated with
this signal, as defined in  \fB<errno.h>\fR\&.
.sp
.LP
\fBsi_code\fR contains a code identifying the cause of the signal.
.sp
.LP
If the value of the  \fBsi_code\fR member is  \fBSI_NOINFO,\fR only the
\fBsi_signo\fR member of  \fBsiginfo_t\fR is meaningful, and the value of all
other members is unspecified.
.SS "User Signals"
.sp
.LP
If the value of  \fBsi_code\fR is less than or equal to 0, then the signal was
generated by a user process (see  \fBkill\fR(2), \fB_lwp_kill\fR(2),
\fBsigqueue\fR(3C), \fBsigsend\fR(2), \fBabort\fR(3C), and \fBraise\fR(3C)) and
the  \fBsiginfo\fR structure contains the following additional information:
.sp
.in +2
.nf
pid_t        si_pid      /* sending process ID */
uid_t        si_uid      /* sending user ID */
ctid_t       si_ctid     /* sending contract ID */
zoneid_t     si_zoneid   /* sending zone ID */S
.fi
.in -2

.sp
.LP
If the signal was generated by a user process, the following values are defined
for \fBsi_code\fR:
.sp
.ne 2
.na
\fB\fBSI_USER\fR \fR
.ad
.RS 15n
The implementation sets \fBsi_code\fR to \fBSI_USER\fR if the signal was sent
by \fBkill\fR(2), \fBsigsend\fR(2), \fBraise\fR(3C) or \fBabort\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBSI_LWP\fR \fR
.ad
.RS 15n
The signal was sent by \fB_lwp_kill\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBSI_QUEUE\fR \fR
.ad
.RS 15n
The signal was sent by \fBsigqueue\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBSI_TIMER\fR \fR
.ad
.RS 15n
The signal was generated by the expiration of a timer created by
\fBtimer_settime\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBSI_ASYNCIO\fR \fR
.ad
.RS 15n
The signal was generated by the completion of an asynchronous  \fBI/O\fR
request.
.RE

.sp
.ne 2
.na
\fB\fBSI_MESGQ\fR \fR
.ad
.RS 15n
The signal was generated by the arrival of a message on an empty message queue.
See \fBmq_notify\fR(3C).
.RE

.sp
.LP
\fBsi_value\fR contains the application specified value, which is passed to the
application's signal-catching function at the time of the signal delivery if
\fBsi_code\fR is any of \fBSI_QUEUE\fR, \fBSI_TIMER\fR, \fBSI_ASYNCHIO\fR, or
\fBSI_MESGQ\fR.
.SS "System Signals"
.sp
.LP
Non-user generated signals can arise for a number of reasons. For all of these
cases, \fBsi_code\fR contains a positive value reflecting the reason why the
system generated the signal:
.sp

.sp
.TS
l l l
l l l .
Signal	Code	Reason
_
SIGILL	ILL_ILLOPC	illegal opcode
	ILL_ILLOPN	illegal operand
	ILL_ILLADR	illegal addressing mode
	ILL_ILLTRP	illegal trap
	ILL_PRVOPC	privileged opcode
	ILL_PRVREG	privileged register
	ILL_COPROC	co-processor error
	ILL_BADSTK	internal stack error
_
SIGFPE	FPE_INTDIV	integer divide by zero
	FPE_INTOVF	integer overflow
	FPE_FLTDIV	floating point divide by zero
	FPE_FLTOVF	floating point overflow
	FPE_FLTUND	floating point underflow
	FPE_FLTRES	floating point inexact result
	FPE_FLTINV	invalid floating point operation
	FPE_FLTSUB	subscript out of range
_
SIGSEGV	SEGV_MAPERR	address not mapped to object
	SEGV_ACCERR	invalid permissions for mapped object
_
SIGBUS	BUS_ADRALN	invalid address alignment
	BUS_ADRERR	non-existent physical address
	BUS_OBJERR	object specific hardware error
_
SIGTRAP	TRAP_BRKPT	process breakpoint
	TRAP_TRACE	process trace trap
_
SIGCHLD	CLD_EXITED	child has exited
	CLD_KILLED	child was killed
	CLD_DUMPED	child terminated abnormally
	CLD_TRAPPED	traced child has trapped
	CLD_STOPPED	child has stopped
	CLD_CONTINUED	stopped child had continued
_
SIGPOLL	POLL_IN	data input available
	POLL_OUT	output buffers available
	POLL_MSG	input message available
	POLL_ERR	I/O error
	POLL_PRI	high priority input available
	POLL_HUP	device disconnected
.TE

.sp
.LP
Signals can also be generated from the resource control subsystem. Where these
signals do not already possess kernel-level \fBsiginfo\fR codes, the
\fBsiginfo\fR \fBsi_code\fR will be filled with \fBSI_RCTL\fR to indicate a
kernel-generated signal from an established resource control value.
.sp

.sp
.TS
c c c
l l l .
Signal	Code	Reason
_
SIGXRES	SI_RCTL	resource-control generated signal
_
SIGHUP		
SIGTERM		
.TE

.sp
.LP
The uncatchable signals \fBSIGSTOP\fR and \fBSIGKILL\fR have undefined
\fBsiginfo\fR codes.
.sp
.LP
Signals sent with a \fBsiginfo\fR code of \fBSI_RCTL\fR contain code-dependent
information for kernel-generated signals:
.sp

.sp
.TS
c c c
l l l .
Code 	Field	Value
_
SI_RCTL	hr_time si_entity	process-model entity of control
.TE

.sp
.LP
In addition, the following signal-dependent information is available for
kernel-generated signals:
.sp

.sp
.TS
c c c
l l l .
Signal	Field	Value
_
SIGILL	caddr_t si_addr	address of faulting instruction
_
SIGFPE		
_
SIGSEGV	caddr_t si_addr	address of faulting memory reference
SIGBUS		
_
SIGCHLD	pid_t si_pid	child process ID
	int si_status	exit value or signal
_
SIGPOLL	long si_band	T{
band event for \fBPOLL_IN\fR, \fBPOLL_OUT\fR, or \fBPOLL_MSG\fR
T}
.TE

.SH SEE ALSO
.sp
.LP
.BR _lwp_kill (2),
.BR kill (2),
.BR setrctl (2),
.BR sigaction (2),
.BR sigsend (2),
.BR waitid (2),
.BR abort (3C),
.BR aio_read (3C),
.BR mq_notify (3C),
.BR raise (3C),
.BR sigqueue (3C),
.BR timer_create (3C),
.BR timer_settime (3C),
.BR signal.h (3HEAD)
.SH NOTES
.sp
.LP
For  \fBSIGCHLD\fR signals, if  \fBsi_code\fR is equal to  \fBCLD_EXITED,\fR
then  \fBsi_status\fR is equal to the exit value of the process; otherwise, it
is equal to the signal that caused the process to  change state. For some
implementations, the exact value of \fBsi_addr\fR might not be available; in
that case, \fBsi_addr\fR is guaranteed to be on the same page as the faulting
instruction or memory reference.