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 September 14, 2012 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 39A process may request signal information when it is catching a signal. 40The information specifies why the system generated that signal. 41To request signal information in a signal handler, the user can set 42.Dv SA_SIGINFO 43in 44.Va sa_flags 45before 46.Xr sigaction 2 47is called, 48otherwise the user can use 49.Xr sigwaitinfo 2 50and 51.Xr sigtimedwait 2 52to get signal information. 53In either case, the system returns the information in a structure of type 54.Vt siginfo_t , 55which includes the following information: 56.Bl -column ".Vt union signal" ".Va si_overrun" 57.It Sy "Type Member Description" 58.It Vt int Ta Va si_signo Ta 59signal number 60.It Vt int Ta Va si_errno Ta 61error number 62.It Vt int Ta Va si_code Ta 63signal code 64.It Vt union sigval Ta Va si_value Ta 65signal value 66.It Vt pid_t Ta Va si_pid Ta 67sending process ID 68.It Vt uid_t Ta Va si_uid Ta 69sending process's real user ID 70.It Vt void Ta Va *si_addr Ta 71address of faulting instruction 72.It Vt int Ta Va si_status Ta 73exit value or signal 74.It Vt long Ta Va si_band Ta 75band event for 76.Dv SIGPOLL 77.It Vt int Ta Va si_trapno Ta 78machine trap code 79.It Vt int Ta Va si_timerid Ta 80.Tn POSIX 81timer ID 82.It Vt int Ta Va si_overrun Ta 83.Tn POSIX 84timer overrun count 85.It Vt int Ta Va si_mqd Ta 86.Tn POSIX 87message queue ID 88.El 89.Pp 90The 91.Va si_signo 92member contains the signal number. 93.Pp 94The 95.Va si_errno 96member contains an error number defined in the file 97.In errno.h . 98.Pp 99The 100.Va si_code 101member contains a code which describes the cause of the signal. 102The macros specified in the 103.Sy Code 104column of the following table are defined 105for use as values of 106.Va si_code 107that are signal-specific or non-signal-specific reasons why the signal was 108generated: 109.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" 110.It Sy "Signal Code Reason" 111.It Dv SIGILL Ta Dv ILL_ILLOPC Ta 112illegal opcode 113.It Ta Dv ILL_ILLOPN Ta 114illegal operand 115.It Ta Dv ILL_ILLADR Ta 116illegal addressing mode 117.It Ta Dv ILL_ILLTRP Ta 118illegal trap 119.It Ta Dv ILL_PRVOPC Ta 120illegal privileged opcode 121.It Ta Dv ILL_PRVREG Ta 122illegal privileged register 123.It Ta Dv ILL_COPROC Ta 124coprocessor error 125.It Ta Dv ILL_BADSTK Ta 126internal stack error 127.It Dv SIGFPE Ta Dv FPE_INTDIV Ta 128integer divide by zero 129.It Ta Dv FPE_INTOVF Ta 130integer overflow 131.It Ta Dv FPE_FLTDIV Ta 132floating-point divide by zero 133.It Ta Dv FPE_FLTOVF Ta 134floating-point overflow 135.It Ta Dv FPE_FLTUND Ta 136floating-point underflow 137.It Ta Dv FPE_FLTRES Ta 138floating-point inexact result 139.It Ta Dv FPE_FLTINV Ta 140invalid floating-point operation 141.It Ta Dv FPE_FLTSUB Ta 142subscript out of range 143.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta 144address not mapped to object 145.It Ta Dv SEGV_ACCERR Ta 146invalid permissions for mapped object 147.It Dv SIGBUS Ta Dv BUS_ADRALN Ta 148invalid address alignment 149.It Ta Dv BUS_ADRERR Ta 150nonexistent physical address 151.It Ta Dv BUS_OBJERR Ta 152object-specific hardware error 153.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta 154process breakpoint 155.It Ta Dv TRAP_TRACE Ta 156process trace trap 157.It Ta Dv TRAP_DTRACE Ta 158DTrace induced trap 159.It Dv SIGCHLD Ta Dv CLD_EXITED Ta 160child has exited 161.It Ta Dv CLD_KILLED Ta 162child has terminated abnormally and did not create a core file 163.It Ta Dv CLD_DUMPED Ta 164child has terminated abnormally and created a core file 165.It Ta Dv CLD_TRAPPED Ta 166traced child has trapped 167.It Ta Dv CLD_STOPPED Ta 168child has stopped 169.It Ta Dv CLD_CONTINUED Ta 170stopped child has continued 171.It Dv SIGPOLL Ta Dv POLL_IN Ta 172data input available 173.It Ta Dv POLL_OUT Ta 174output buffers available 175.It Ta Dv POLL_MSG Ta 176input message available 177.It Ta Dv POLL_ERR Ta 178I/O error 179.It Ta Dv POLL_PRI Ta 180high priority input available 181.It Ta Dv POLL_HUP Ta 182device disconnected 183.It Any Ta Dv SI_NOINFO Ta 184Only the 185.Va si_signo 186member is meaningful; the value of all other members is unspecified. 187.It Ta Dv SI_USER Ta 188signal sent by 189.Xr kill 2 190.It Ta Dv SI_QUEUE Ta 191signal sent by 192.Xr sigqueue 2 193.It Ta Dv SI_TIMER Ta 194signal generated by expiration of a timer set by 195.Xr timer_settime 2 196.It Ta Dv SI_ASYNCIO Ta 197signal generated by completion of an asynchronous I/O request 198.It Ta Dv SI_MESGQ Ta 199signal generated by arrival of a message on an empty message queue 200.It Ta Dv SI_KERNEL Ta 201signal generated by miscellaneous parts of the kernel 202.It Ta Dv SI_LWP Ta 203signal sent by 204.Xr pthread_kill 3 205.El 206.Pp 207In addition, the following signal-specific information is available: 208.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" 209.It Sy "Signal Member Value" 210.It Dv SIGILL Ta Va si_addr Ta 211address of faulting instruction 212.It Ta Va si_trapno Ta 213machine dependent of trap code 214.It Dv SIGFPE Ta Va si_addr Ta 215address of faulting instruction 216.It Ta Va si_trapno Ta 217machine dependent of trap code 218.It Dv SIGSEGV Ta Va si_addr Ta 219address of faulting memory reference 220.It Ta Va si_trapno Ta 221machine dependent of trap code 222.It Dv SIGBUS Ta Va si_addr Ta 223address of faulting instruction 224.It Ta Va si_trapno Ta 225machine dependent of trap code 226.It Dv SIGCHLD Ta Va si_pid Ta 227child process ID 228.It Ta Va si_status Ta 229exit value or signal; if 230.Va si_code 231is equal to 232.Dv CLD_EXITED , 233then it is equal to the exit value of the child process, otherwise, 234it is equal to a signal that caused the child process to change state. 235.It Ta Va si_uid Ta "real user ID of the process that sent the signal" 236.It Dv SIGPOLL Ta Va si_band Ta "band event for" 237.Dv POLL_IN , POLL_OUT , 238or 239.Dv POLL_MSG 240.El 241.Pp 242Finally, the following code-specific information is available: 243.Bl -column ".Dv SI_QUEUE" ".Va si_overrun" 244.It Sy "Code Member Value" 245.It Dv SI_USER Ta Va si_pid Ta 246the process ID that sent the signal 247.It Ta Va si_uid Ta 248real user ID of the process that sent the signal 249.It Dv SI_QUEUE Ta Va si_value Ta 250the value passed to 251.Xr sigqueue 2 252system call 253.It Ta Va si_pid Ta 254the process ID that sent the signal 255.It Ta Va si_uid Ta 256real user ID of the process that sent the signal 257.It Dv SI_TIMER Ta Va si_value Ta 258the value passed to 259.Xr timer_create 2 260system call 261.It Ta Va si_timerid Ta 262the timer ID returned by 263.Xr timer_create 2 264system call 265.It Ta Va si_overrun Ta 266timer overrun count corresponding to the signal 267.It Ta Va si_errno Ta 268If timer overrun will be 269.Brq Dv DELAYTIMER_MAX , 270an error code defined in 271.In errno.h 272is set 273.It Dv SI_ASYNCIO Ta Va si_value Ta 274the value passed to aio system calls 275.It Dv SI_MESGQ Ta Va si_value Ta 276the value passed to 277.Xr mq_notify 2 278system call 279.It Ta Va si_mqd Ta 280the ID of the message queue which generated the signal 281.It Dv SI_LWP Ta Va si_pid Ta 282the process ID that sent the signal 283.It Ta Va si_uid Ta 284real user ID of the process that sent the signal 285.El 286.Sh NOTES 287Currently, the kernel never generates the 288.Dv SIGPOLL 289signal. 290.Dv SIGCHLD 291signal is queued when a process changed its status or exited. 292.Tn POSIX 293Realtime Extensions like aio, timer, and message queue also queue 294signals. 295Signals with code 296.Dv SI_USER , 297.Dv SI_KERNEL 298or 299.Dv SI_LWP 300are only queued if there are sufficient resources; 301otherwise, 302.Dv SI_NOINFO 303results. 304For some hardware architectures, the exact value of 305.Va si_addr 306might not be available. 307.Sh SEE ALSO 308.Xr aio_read 2 , 309.Xr kill 2 , 310.Xr mq_notify 2 , 311.Xr sigaction 2 , 312.Xr sigqueue 2 , 313.Xr sigwaitinfo 2 , 314.Xr timer_create 2 , 315.Xr timer_settime 2 , 316.Xr waitpid 2 , 317.Xr pthread_kill 3 318.Sh STANDARDS 319The 320.Vt siginfo_t 321type conforms to 322.St -p1003.1-2004 . 323.Sh HISTORY 324Full support for 325.Tn POSIX 326signal information first appeared in 327.Fx 7.0 . 328The codes 329.Dv SI_USER 330and 331.Dv SI_KERNEL 332can be generated as of 333.Fx 8.1 . 334The code 335.Dv SI_LWP 336can be generated as of 337.Fx 9.0 . 338.Sh AUTHORS 339This manual page was written by 340.An David Xu Aq Mt davidxu@FreeBSD.org . 341