usr/src/man/man3head/siginfo.h.3head

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH SIGINFO.H 3HEAD "Feb 5, 2008"
   8 .SH NAME
   9 siginfo.h, siginfo \- signal generation information
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <siginfo.h>
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 If a process is catching a signal,  it might request information that tells why
  20 the system generated that signal. See  \fBsigaction\fR(2). If a process is
  21 monitoring its children, it might receive information that tells why a child
  22 changed state. See  \fBwaitid\fR(2). In either case, the system returns the
  23 information in a structure of type  \fBsiginfo_t\fR, which includes the
  24 following information:
  25 .sp
  26 .in +2
  27 .nf
  28 int            si_signo        /* signal number */
  29 int            si_errno        /* error number */
  30 int            si_code         /* signal code */
  31 union sigval   si_value        /* signal value */
  32 .fi
  33 .in -2
  34
  35 .sp
  36 .LP
  37 \fBsi_signo\fR contains the system-generated signal number. For the
  38 \fBwaitid\fR(2) function,  \fBsi_signo\fR is always  \fBSIGCHLD\fR.
  39 .sp
  40 .LP
  41 If  \fBsi_errno\fR is non-zero, it contains an error number associated with
  42 this signal, as defined in  \fB<errno.h>\fR\&.
  43 .sp
  44 .LP
  45 \fBsi_code\fR contains a code identifying the cause of the signal.
  46 .sp
  47 .LP
  48 If the value of the  \fBsi_code\fR member is  \fBSI_NOINFO,\fR only the
  49 \fBsi_signo\fR member of  \fBsiginfo_t\fR is meaningful, and the value of all
  50 other members is unspecified.
  51 .SS "User Signals"
  52 .sp
  53 .LP
  54 If the value of  \fBsi_code\fR is less than or equal to 0, then the signal was
  55 generated by a user process (see  \fBkill\fR(2), \fB_lwp_kill\fR(2),
  56 \fBsigqueue\fR(3C), \fBsigsend\fR(2), \fBabort\fR(3C), and \fBraise\fR(3C)) and
  57 the  \fBsiginfo\fR structure contains the following additional information:
  58 .sp
  59 .in +2
  60 .nf
  61 pid_t        si_pid      /* sending process ID */
  62 uid_t        si_uid      /* sending user ID */
  63 ctid_t       si_ctid     /* sending contract ID */
  64 zoneid_t     si_zoneid   /* sending zone ID */S
  65 .fi
  66 .in -2
  67
  68 .sp
  69 .LP
  70 If the signal was generated by a user process, the following values are defined
  71 for \fBsi_code\fR:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBSI_USER\fR \fR
  76 .ad
  77 .RS 15n
  78 The implementation sets \fBsi_code\fR to \fBSI_USER\fR if the signal was sent
  79 by \fBkill\fR(2), \fBsigsend\fR(2), \fBraise\fR(3C) or \fBabort\fR(3C).
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBSI_LWP\fR \fR
  86 .ad
  87 .RS 15n
  88 The signal was sent by \fB_lwp_kill\fR(2).
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBSI_QUEUE\fR \fR
  95 .ad
  96 .RS 15n
  97 The signal was sent by \fBsigqueue\fR(3C).
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBSI_TIMER\fR \fR
 104 .ad
 105 .RS 15n
 106 The signal was generated by the expiration of a timer created by
 107 \fBtimer_settime\fR(3C).
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBSI_ASYNCIO\fR \fR
 114 .ad
 115 .RS 15n
 116 The signal was generated by the completion of an asynchronous  \fBI/O\fR
 117 request.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBSI_MESGQ\fR \fR
 124 .ad
 125 .RS 15n
 126 The signal was generated by the arrival of a message on an empty message queue.
 127 See \fBmq_notify\fR(3C).
 128 .RE
 129
 130 .sp
 131 .LP
 132 \fBsi_value\fR contains the application specified value, which is passed to the
 133 application's signal-catching function at the time of the signal delivery if
 134 \fBsi_code\fR is any of \fBSI_QUEUE\fR, \fBSI_TIMER\fR, \fBSI_ASYNCHIO\fR, or
 135 \fBSI_MESGQ\fR.
 136 .SS "System Signals"
 137 .sp
 138 .LP
 139 Non-user generated signals can arise for a number of reasons. For all of these
 140 cases, \fBsi_code\fR contains a positive value reflecting the reason why the
 141 system generated the signal:
 142 .sp
 143
 144 .sp
 145 .TS
 146 l l l
 147 l l l .
 148 Signal  Code    Reason
 149 _
 150 SIGILL  ILL_ILLOPC      illegal opcode
 151         ILL_ILLOPN      illegal operand
 152         ILL_ILLADR      illegal addressing mode
 153         ILL_ILLTRP      illegal trap
 154         ILL_PRVOPC      privileged opcode
 155         ILL_PRVREG      privileged register
 156         ILL_COPROC      co-processor error
 157         ILL_BADSTK      internal stack error
 158 _
 159 SIGFPE  FPE_INTDIV      integer divide by zero
 160         FPE_INTOVF      integer overflow
 161         FPE_FLTDIV      floating point divide by zero
 162         FPE_FLTOVF      floating point overflow
 163         FPE_FLTUND      floating point underflow
 164         FPE_FLTRES      floating point inexact result
 165         FPE_FLTINV      invalid floating point operation
 166         FPE_FLTSUB      subscript out of range
 167 _
 168 SIGSEGV SEGV_MAPERR     address not mapped to object
 169         SEGV_ACCERR     invalid permissions for mapped object
 170 _
 171 SIGBUS  BUS_ADRALN      invalid address alignment
 172         BUS_ADRERR      non-existent physical address
 173         BUS_OBJERR      object specific hardware error
 174 _
 175 SIGTRAP TRAP_BRKPT      process breakpoint
 176         TRAP_TRACE      process trace trap
 177 _
 178 SIGCHLD CLD_EXITED      child has exited
 179         CLD_KILLED      child was killed
 180         CLD_DUMPED      child terminated abnormally
 181         CLD_TRAPPED     traced child has trapped
 182         CLD_STOPPED     child has stopped
 183         CLD_CONTINUED   stopped child had continued
 184 _
 185 SIGPOLL POLL_IN data input available
 186         POLL_OUT        output buffers available
 187         POLL_MSG        input message available
 188         POLL_ERR        I/O error
 189         POLL_PRI        high priority input available
 190         POLL_HUP        device disconnected
 191 .TE
 192
 193 .sp
 194 .LP
 195 Signals can also be generated from the resource control subsystem. Where these
 196 signals do not already possess kernel-level \fBsiginfo\fR codes, the
 197 \fBsiginfo\fR \fBsi_code\fR will be filled with \fBSI_RCTL\fR to indicate a
 198 kernel-generated signal from an established resource control value.
 199 .sp
 200
 201 .sp
 202 .TS
 203 c c c
 204 l l l .
 205 Signal  Code    Reason
 206 _
 207 SIGXRES SI_RCTL resource-control generated signal
 208 _
 209 SIGHUP
 210 SIGTERM
 211 .TE
 212
 213 .sp
 214 .LP
 215 The uncatchable signals \fBSIGSTOP\fR and \fBSIGKILL\fR have undefined
 216 \fBsiginfo\fR codes.
 217 .sp
 218 .LP
 219 Signals sent with a \fBsiginfo\fR code of \fBSI_RCTL\fR contain code-dependent
 220 information for kernel-generated signals:
 221 .sp
 222
 223 .sp
 224 .TS
 225 c c c
 226 l l l .
 227 Code    Field   Value
 228 _
 229 SI_RCTL hr_time si_entity       process-model entity of control
 230 .TE
 231
 232 .sp
 233 .LP
 234 In addition, the following signal-dependent information is available for
 235 kernel-generated signals:
 236 .sp
 237
 238 .sp
 239 .TS
 240 c c c
 241 l l l .
 242 Signal  Field   Value
 243 _
 244 SIGILL  caddr_t si_addr address of faulting instruction
 245 _
 246 SIGFPE
 247 _
 248 SIGSEGV caddr_t si_addr address of faulting memory reference
 249 SIGBUS
 250 _
 251 SIGCHLD pid_t si_pid    child process ID
 252         int si_status   exit value or signal
 253 _
 254 SIGPOLL long si_band    T{
 255 band event for \fBPOLL_IN\fR, \fBPOLL_OUT\fR, or \fBPOLL_MSG\fR
 256 T}
 257 .TE
 258
 259 .SH SEE ALSO
 260 .sp
 261 .LP
 262 \fB_lwp_kill\fR(2), \fBkill\fR(2), \fBsetrctl\fR(2), \fBsigaction\fR(2),
 263 \fBsigsend\fR(2), \fBwaitid\fR(2), \fBabort\fR(3C), \fBaio_read\fR(3C),
 264 \fBmq_notify\fR(3C), \fBraise\fR(3C), \fBsignal.h\fR(3HEAD),
 265 \fBsigqueue\fR(3C), \fBtimer_create\fR(3C), \fBtimer_settime\fR(3C)
 266 .SH NOTES
 267 .sp
 268 .LP
 269 For  \fBSIGCHLD\fR signals, if  \fBsi_code\fR is equal to  \fBCLD_EXITED,\fR
 270 then  \fBsi_status\fR is equal to the exit value of the process; otherwise, it
 271 is equal to the signal that caused the process to  change state. For some
 272 implementations, the exact value of \fBsi_addr\fR might not be available; in
 273 that case, \fBsi_addr\fR is guaranteed to be on the same page as the faulting
 274 instruction or memory reference.