share/man/man3/siginfo.3

   1 .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd May 8, 2020
  31 .Dt SIGINFO 3
  32 .Os
  33 .Sh NAME
  34 .Nm siginfo
  35 .Nd "signal generation information"
  36 .Sh SYNOPSIS
  37 .In signal.h
  38 .Sh DESCRIPTION
  39 A process may request signal information when it is catching a signal.
  40 The information specifies why the system generated that signal.
  41 To request signal information in a signal handler, the user can set
  42 .Dv SA_SIGINFO
  43 in
  44 .Va sa_flags
  45 before
  46 .Xr sigaction 2
  47 is called,
  48 otherwise the user can use
  49 .Xr sigwaitinfo 2
  50 and
  51 .Xr sigtimedwait 2
  52 to get signal information.
  53 In either case, the system returns the information in a structure of type
  54 .Vt siginfo_t ,
  55 which includes the following information:
  56 .Bl -column ".Vt union signal" ".Va si_overrun"
  57 .It Sy Type Ta Sy Member Ta Sy Description
  58 .It Vt int Ta Va si_signo Ta
  59 signal number
  60 .It Vt int Ta Va si_errno Ta
  61 error number
  62 .It Vt int Ta Va si_code Ta
  63 signal code
  64 .It Vt union sigval Ta Va si_value Ta
  65 signal value
  66 .It Vt pid_t Ta Va si_pid Ta
  67 sending process ID
  68 .It Vt uid_t Ta Va si_uid Ta
  69 sending process's real user ID
  70 .It Vt void Ta Va *si_addr Ta
  71 address of faulting instruction
  72 .It Vt int Ta Va si_status Ta
  73 exit value or signal
  74 .It Vt long Ta Va si_band Ta
  75 band event for
  76 .Dv SIGPOLL
  77 .It Vt int Ta Va si_trapno Ta
  78 machine trap code
  79 .It Vt int Ta Va si_timerid Ta
  80 .Tn POSIX
  81 timer ID
  82 .It Vt int Ta Va si_overrun Ta
  83 .Tn POSIX
  84 timer overrun count
  85 .It Vt int Ta Va si_mqd Ta
  86 .Tn POSIX
  87 message queue ID
  88 .El
  89 .Pp
  90 The
  91 .Va si_signo
  92 member contains the signal number.
  93 .Pp
  94 The
  95 .Va si_errno
  96 member contains an error number defined in the file
  97 .In errno.h .
  98 .Pp
  99 The
 100 .Va si_code
 101 member contains a code which describes the cause of the signal.
 102 The macros specified in the
 103 .Sy Code
 104 column of the following table are defined
 105 for use as values of
 106 .Va si_code
 107 that are signal-specific or non-signal-specific reasons why the signal was
 108 generated:
 109 .Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
 110 .It Sy Signal Ta Sy Code Ta Sy Reason
 111 .It Dv SIGILL Ta Dv ILL_ILLOPC Ta
 112 illegal opcode
 113 .It Ta Dv ILL_ILLOPN Ta
 114 illegal operand
 115 .It Ta Dv ILL_ILLADR Ta
 116 illegal addressing mode
 117 .It Ta Dv ILL_ILLTRP Ta
 118 illegal trap
 119 .It Ta Dv ILL_PRVOPC Ta
 120 illegal privileged opcode
 121 .It Ta Dv ILL_PRVREG Ta
 122 illegal privileged register
 123 .It Ta Dv ILL_COPROC Ta
 124 coprocessor error
 125 .It Ta Dv ILL_BADSTK Ta
 126 internal stack error
 127 .It Dv SIGFPE Ta Dv FPE_INTDIV Ta
 128 integer divide by zero
 129 .It Ta Dv FPE_INTOVF Ta
 130 integer overflow
 131 .It Ta Dv FPE_FLTDIV Ta
 132 floating-point divide by zero
 133 .It Ta Dv FPE_FLTOVF Ta
 134 floating-point overflow
 135 .It Ta Dv FPE_FLTUND Ta
 136 floating-point underflow
 137 .It Ta Dv FPE_FLTRES Ta
 138 floating-point inexact result
 139 .It Ta Dv FPE_FLTINV Ta
 140 invalid floating-point operation
 141 .It Ta Dv FPE_FLTSUB Ta
 142 subscript out of range
 143 .It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta
 144 address not mapped to object
 145 .It Ta Dv SEGV_ACCERR Ta
 146 invalid permissions for mapped object
 147 .It Dv SIGBUS Ta Dv BUS_ADRALN Ta
 148 invalid address alignment
 149 .It Ta Dv BUS_ADRERR Ta
 150 nonexistent physical address
 151 .It Ta Dv BUS_OBJERR Ta
 152 object-specific hardware error
 153 .It Ta Dv BUS_OOMERR Ta
 154 cannot alloc a page to map at fault
 155 .It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
 156 process breakpoint
 157 .It Ta Dv TRAP_TRACE Ta
 158 process trace trap
 159 .It Ta Dv TRAP_DTRACE Ta
 160 DTrace induced trap
 161 .It Ta Dv TRAP_CAP Ta
 162 capabilities protective trap
 163 .It Dv SIGCHLD Ta Dv CLD_EXITED Ta
 164 child has exited
 165 .It Ta Dv CLD_KILLED Ta
 166 child has terminated abnormally and did not create a core file
 167 .It Ta Dv CLD_DUMPED Ta
 168 child has terminated abnormally and created a core file
 169 .It Ta Dv CLD_TRAPPED Ta
 170 traced child has trapped
 171 .It Ta Dv CLD_STOPPED Ta
 172 child has stopped
 173 .It Ta Dv CLD_CONTINUED Ta
 174 stopped child has continued
 175 .It Dv SIGPOLL Ta Dv POLL_IN Ta
 176 data input available
 177 .It Ta Dv POLL_OUT Ta
 178 output buffers available
 179 .It Ta Dv POLL_MSG Ta
 180 input message available
 181 .It Ta Dv POLL_ERR Ta
 182 I/O error
 183 .It Ta Dv POLL_PRI Ta
 184 high priority input available
 185 .It Ta Dv POLL_HUP Ta
 186 device disconnected
 187 .It Any Ta Dv SI_NOINFO Ta
 188 Only the
 189 .Va si_signo
 190 member is meaningful; the value of all other members is unspecified.
 191 .It Ta Dv SI_USER Ta
 192 signal sent by
 193 .Xr kill 2
 194 .It Ta Dv SI_QUEUE Ta
 195 signal sent by
 196 .Xr sigqueue 2
 197 .It Ta Dv SI_TIMER Ta
 198 signal generated by expiration of a timer set by
 199 .Xr timer_settime 2
 200 .It Ta Dv SI_ASYNCIO Ta
 201 signal generated by completion of an asynchronous I/O request
 202 .It Ta Dv SI_MESGQ Ta
 203 signal generated by arrival of a message on an empty message queue
 204 .It Ta Dv SI_KERNEL Ta
 205 signal generated by miscellaneous parts of the kernel
 206 .It Ta Dv SI_LWP Ta
 207 signal sent by
 208 .Xr pthread_kill 3
 209 .El
 210 .Pp
 211 In addition, the following signal-specific information is available:
 212 .Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
 213 .It Sy Signal Ta Sy Member Ta Sy Value
 214 .It Dv SIGILL Ta Va si_addr Ta
 215 address of faulting instruction
 216 .It Ta Va si_trapno Ta
 217 machine dependent of trap code
 218 .It Dv SIGFPE Ta Va si_addr Ta
 219 address of faulting instruction
 220 .It Ta Va si_trapno Ta
 221 machine dependent of trap code
 222 .It Dv SIGSEGV Ta Va si_addr Ta
 223 address of faulting memory reference
 224 .It Ta Va si_trapno Ta
 225 machine dependent of trap code
 226 .It Dv SIGBUS Ta Va si_addr Ta
 227 address of faulting instruction
 228 .It Ta Va si_trapno Ta
 229 machine dependent of trap code
 230 .It Dv SIGCHLD Ta Va si_pid Ta
 231 child process ID
 232 .It Ta Va si_status Ta
 233 exit value or signal; if
 234 .Va si_code
 235 is equal to
 236 .Dv CLD_EXITED ,
 237 then it is equal to the exit value of the child process, otherwise,
 238 it is equal to a signal that caused the child process to change state.
 239 .It Ta Va si_uid Ta "real user ID of the process that sent the signal"
 240 .It Dv SIGPOLL Ta Va si_band Ta "band event for"
 241 .Dv POLL_IN , POLL_OUT ,
 242 or
 243 .Dv POLL_MSG
 244 .El
 245 .Pp
 246 Finally, the following code-specific information is available:
 247 .Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun"
 248 .It Sy Code Ta Sy Member Ta Sy Value
 249 .It Dv SI_USER Ta Va si_pid Ta
 250 the process ID that sent the signal
 251 .It Ta Va si_uid Ta
 252 real user ID of the process that sent the signal
 253 .It Dv SI_QUEUE Ta Va si_value Ta
 254 the value passed to
 255 .Xr sigqueue 2
 256 system call
 257 .It Ta Va si_pid Ta
 258 the process ID that sent the signal
 259 .It Ta Va si_uid Ta
 260 real user ID of the process that sent the signal
 261 .It Dv SI_TIMER Ta Va si_value Ta
 262 the value passed to
 263 .Xr timer_create 2
 264 system call
 265 .It Ta Va si_timerid Ta
 266 the timer ID returned by
 267 .Xr timer_create 2
 268 system call
 269 .It Ta Va si_overrun Ta
 270 timer overrun count corresponding to the signal
 271 .It Ta Va si_errno Ta
 272 If timer overrun will be
 273 .Brq Dv DELAYTIMER_MAX ,
 274 an error code defined in
 275 .In errno.h
 276 is set
 277 .It Dv SI_ASYNCIO Ta Va si_value Ta
 278 the value passed to aio system calls
 279 .It Dv SI_MESGQ Ta Va si_value Ta
 280 the value passed to
 281 .Xr mq_notify 2
 282 system call
 283 .It Ta Va si_mqd Ta
 284 the ID of the message queue which generated the signal
 285 .It Dv SI_LWP Ta Va si_pid Ta
 286 the process ID that sent the signal
 287 .It Ta Va si_uid Ta
 288 real user ID of the process that sent the signal
 289 .El
 290 .Sh NOTES
 291 Currently, the kernel never generates the
 292 .Dv SIGPOLL
 293 signal.
 294 .Dv SIGCHLD
 295 signal is queued when a process changed its status or exited.
 296 .Tn POSIX
 297 Realtime Extensions like aio, timer, and message queue also queue
 298 signals.
 299 Signals with code
 300 .Dv SI_USER ,
 301 .Dv SI_KERNEL
 302 or
 303 .Dv SI_LWP
 304 are only queued if there are sufficient resources;
 305 otherwise,
 306 .Dv SI_NOINFO
 307 results.
 308 For some hardware architectures, the exact value of
 309 .Va si_addr
 310 might not be available.
 311 .Sh SEE ALSO
 312 .Xr aio_read 2 ,
 313 .Xr kill 2 ,
 314 .Xr mq_notify 2 ,
 315 .Xr sigaction 2 ,
 316 .Xr sigqueue 2 ,
 317 .Xr sigwaitinfo 2 ,
 318 .Xr timer_create 2 ,
 319 .Xr timer_settime 2 ,
 320 .Xr waitpid 2 ,
 321 .Xr pthread_kill 3
 322 .Sh STANDARDS
 323 The
 324 .Vt siginfo_t
 325 type conforms to
 326 .St -p1003.1-2004 .
 327 .Sh HISTORY
 328 Full support for
 329 .Tn POSIX
 330 signal information first appeared in
 331 .Fx 7.0 .
 332 The codes
 333 .Dv SI_USER
 334 and
 335 .Dv SI_KERNEL
 336 can be generated as of
 337 .Fx 8.1 .
 338 The code
 339 .Dv SI_LWP
 340 can be generated as of
 341 .Fx 9.0 .
 342 .Sh AUTHORS
 343 This manual page was written by
 344 .An David Xu Aq Mt davidxu@FreeBSD.org .