| blob | 6e6b2a4cd6461b55cfc5978ca066a1a37bdd5b4b |
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 December 8, 2005
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 Member 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 Code 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 Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
154 process breakpoint
155 .It Ta Dv TRAP_TRACE Ta
156 process trace trap
157 .It Dv SIGCHLD Ta Dv CLD_EXITED Ta
158 child has exited
159 .It Ta Dv CLD_KILLED Ta
160 child has terminated abnormally and did not create a core file
161 .It Ta Dv CLD_DUMPED Ta
162 child has terminated abnormally and created a core file
163 .It Ta Dv CLD_TRAPPED Ta
164 traced child has trapped
165 .It Ta Dv CLD_STOPPED Ta
166 child has stopped
167 .It Ta Dv CLD_CONTINUED Ta
168 stopped child has continued
169 .It Dv SIGPOLL Ta Dv POLL_IN Ta
170 data input available
171 .It Ta Dv POLL_OUT Ta
172 output buffers available
173 .It Ta Dv POLL_MSG Ta
174 input message available
175 .It Ta Dv POLL_ERR Ta
176 I/O error
177 .It Ta Dv POLL_PRI Ta
178 high priority input available
179 .It Ta Dv POLL_HUP Ta
180 device disconnected
181 .It Any Ta Dv SI_NOINFO Ta
182 Only the
183 .Va si_signo
184 member is meaningful; the value of all other members is unspecified.
185 .It Ta Dv SI_USER Ta
186 signal sent by
187 .Xr kill 2
188 .It Ta Dv SI_QUEUE Ta
189 signal sent by
190 .Xr sigqueue 2
191 .It Ta Dv SI_TIMER Ta
192 signal generated by expiration of a timer set by
193 .Xr timer_settime 2
194 .It Ta Dv SI_ASYNCIO Ta
195 signal generated by completion of an asynchronous I/O request
196 .It Ta Dv SI_MESGQ Ta
197 signal generated by arrival of a message on an empty message queue
198 .El
199 .Pp
200 In addition, the following signal-specific information is available:
201 .Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
202 .It Sy "Signal Member Value"
203 .It Dv SIGILL Ta Va si_addr Ta
204 address of faulting instruction
205 .It Ta Va si_trapno Ta
206 machine dependent of trap code
207 .It Dv SIGFPE Ta Va si_addr Ta
208 address of faulting instruction
209 .It Ta Va si_trapno Ta
210 machine dependent of trap code
211 .It Dv SIGSEGV Ta Va si_addr Ta
212 address of faulting memory reference
213 .It Ta Va si_trapno Ta
214 machine dependent of trap code
215 .It Dv SIGBUS Ta Va si_addr Ta
216 address of faulting instruction
217 .It Ta Va si_trapno Ta
218 machine dependent of trap code
219 .It Dv SIGCHLD Ta Vt Va si_pid Ta
220 child process ID
221 .It Ta Va si_status Ta
222 exit value or signal; if
223 .Va si_code
224 is equal to
225 .Dv CLD_EXITED ,
226 then it is equal to the exit value of the child process, otherwise,
227 it is equal to a signal that caused the child process to change state.
228 .It Ta Va si_uid Ta "real user ID of the process that sent the signal"
229 .It Dv SIGPOLL Ta Va si_band Ta "band event for"
230 .Dv POLL_IN , POLL_OUT ,
231 or
232 .Dv POLL_MSG
233 .El
234 .Pp
235 Finally, the following code-specific information is available:
236 .Bl -column ".Dv SI_QUEUE" ".Va si_overrun"
237 .It Sy "Code Member Value"
238 .It Dv SI_QUEUE Ta Va si_value Ta
239 the value passed to
240 .Xr sigqueue 2
241 system call
242 .It Ta Va si_pid Ta
243 the process ID that sent the signal
244 .It Ta Va si_uid Ta
245 real user ID of the process that sent the signal
246 .It Dv SI_TIMER Ta Va si_value Ta
247 the value passed to
248 .Xr timer_create 2
249 system call
250 .It Ta Va si_timerid Ta
251 the timer ID returned by
252 .Xr timer_create 2
253 system call
254 .It Ta Va si_overrun Ta
255 timer overrun count corresponding to the signal
256 .It Ta Va si_errno Ta
257 If timer overrun will be
258 .Brq Dv DELAYTIMER_MAX ,
259 an error code defined in
260 .In errno.h
261 is set
262 .It Dv SI_ASYNCIO Ta Va si_value Ta
263 the value passed to aio system calls
264 .It Dv SI_MESGQ Ta Va si_value Ta
265 the value passed to
266 .Xr mq_notify 2
267 system call
268 .It Ta Va si_mqd Ta
269 the ID of the message queue which generated the signal
270 .El
271 .Sh NOTES
272 Currently, the kernel never generates the
273 .Dv SIGPOLL
274 signal.
275 Also, the
276 .Xr kill 2
277 system call does not queue signals, so you will not get code
278 .Dv SI_USER .
279 .Dv SIGCHLD
280 signal is queued when a process changed its status or exited.
281 .Tn POSIX
282 Realtime Extensions like aio, timer, and message queue also queue
283 signals.
284 For some hardware architectures, the exact value of
285 .Va si_addr
286 might not be available.
287 .Sh SEE ALSO
288 .Xr aio_read 2 ,
289 .Xr kill 2 ,
290 .Xr mq_notify 2 ,
291 .Xr sigaction 2 ,
292 .Xr sigqueue 2 ,
293 .Xr sigwaitinfo 2 ,
294 .Xr timer_create 2 ,
295 .Xr timer_settime 2 ,
296 .Xr waitpid 2
297 .Sh STANDARDS
298 The
299 .Vt siginfo_t
300 type conforms to
301 .St -p1003.1-2004 .
302 .Sh HISTORY
303 Full support for
304 .Tn POSIX
305 signal information first appeared in
306 .Fx 7.0 .
307 .Sh AUTHORS
308 This manual page was written by
309 .An "David Xu" Aq davidxu@FreeBSD.org .