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