xref: /freebsd/share/man/man3/siginfo.3 (revision e17f5b1d)
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
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 Ta Sy Member Ta Sy 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 Ta Sy Code Ta Sy 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 Ta Dv BUS_OOMERR Ta
154cannot alloc a page to map at fault
155.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
156process breakpoint
157.It Ta Dv TRAP_TRACE Ta
158process trace trap
159.It Ta Dv TRAP_DTRACE Ta
160DTrace induced trap
161.It Ta Dv TRAP_CAP Ta
162capabilities protective trap
163.It Dv SIGCHLD Ta Dv CLD_EXITED Ta
164child has exited
165.It Ta Dv CLD_KILLED Ta
166child has terminated abnormally and did not create a core file
167.It Ta Dv CLD_DUMPED Ta
168child has terminated abnormally and created a core file
169.It Ta Dv CLD_TRAPPED Ta
170traced child has trapped
171.It Ta Dv CLD_STOPPED Ta
172child has stopped
173.It Ta Dv CLD_CONTINUED Ta
174stopped child has continued
175.It Dv SIGPOLL Ta Dv POLL_IN Ta
176data input available
177.It Ta Dv POLL_OUT Ta
178output buffers available
179.It Ta Dv POLL_MSG Ta
180input message available
181.It Ta Dv POLL_ERR Ta
182I/O error
183.It Ta Dv POLL_PRI Ta
184high priority input available
185.It Ta Dv POLL_HUP Ta
186device disconnected
187.It Any Ta Dv SI_NOINFO Ta
188Only the
189.Va si_signo
190member is meaningful; the value of all other members is unspecified.
191.It Ta Dv SI_USER Ta
192signal sent by
193.Xr kill 2
194.It Ta Dv SI_QUEUE Ta
195signal sent by
196.Xr sigqueue 2
197.It Ta Dv SI_TIMER Ta
198signal generated by expiration of a timer set by
199.Xr timer_settime 2
200.It Ta Dv SI_ASYNCIO Ta
201signal generated by completion of an asynchronous I/O request
202.It Ta Dv SI_MESGQ Ta
203signal generated by arrival of a message on an empty message queue
204.It Ta Dv SI_KERNEL Ta
205signal generated by miscellaneous parts of the kernel
206.It Ta Dv SI_LWP Ta
207signal sent by
208.Xr pthread_kill 3
209.El
210.Pp
211In 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
215address of faulting instruction
216.It Ta Va si_trapno Ta
217machine dependent of trap code
218.It Dv SIGFPE Ta Va si_addr Ta
219address of faulting instruction
220.It Ta Va si_trapno Ta
221machine dependent of trap code
222.It Dv SIGSEGV Ta Va si_addr Ta
223address of faulting memory reference
224.It Ta Va si_trapno Ta
225machine dependent of trap code
226.It Dv SIGBUS Ta Va si_addr Ta
227address of faulting instruction
228.It Ta Va si_trapno Ta
229machine dependent of trap code
230.It Dv SIGCHLD Ta Va si_pid Ta
231child process ID
232.It Ta Va si_status Ta
233exit value or signal; if
234.Va si_code
235is equal to
236.Dv CLD_EXITED ,
237then it is equal to the exit value of the child process, otherwise,
238it 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 ,
242or
243.Dv POLL_MSG
244.El
245.Pp
246Finally, 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
250the process ID that sent the signal
251.It Ta Va si_uid Ta
252real user ID of the process that sent the signal
253.It Dv SI_QUEUE Ta Va si_value Ta
254the value passed to
255.Xr sigqueue 2
256system call
257.It Ta Va si_pid Ta
258the process ID that sent the signal
259.It Ta Va si_uid Ta
260real user ID of the process that sent the signal
261.It Dv SI_TIMER Ta Va si_value Ta
262the value passed to
263.Xr timer_create 2
264system call
265.It Ta Va si_timerid Ta
266the timer ID returned by
267.Xr timer_create 2
268system call
269.It Ta Va si_overrun Ta
270timer overrun count corresponding to the signal
271.It Ta Va si_errno Ta
272If timer overrun will be
273.Brq Dv DELAYTIMER_MAX ,
274an error code defined in
275.In errno.h
276is set
277.It Dv SI_ASYNCIO Ta Va si_value Ta
278the value passed to aio system calls
279.It Dv SI_MESGQ Ta Va si_value Ta
280the value passed to
281.Xr mq_notify 2
282system call
283.It Ta Va si_mqd Ta
284the ID of the message queue which generated the signal
285.It Dv SI_LWP Ta Va si_pid Ta
286the process ID that sent the signal
287.It Ta Va si_uid Ta
288real user ID of the process that sent the signal
289.El
290.Sh NOTES
291Currently, the kernel never generates the
292.Dv SIGPOLL
293signal.
294.Dv SIGCHLD
295signal is queued when a process changed its status or exited.
296.Tn POSIX
297Realtime Extensions like aio, timer, and message queue also queue
298signals.
299Signals with code
300.Dv SI_USER ,
301.Dv SI_KERNEL
302or
303.Dv SI_LWP
304are only queued if there are sufficient resources;
305otherwise,
306.Dv SI_NOINFO
307results.
308For some hardware architectures, the exact value of
309.Va si_addr
310might 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
323The
324.Vt siginfo_t
325type conforms to
326.St -p1003.1-2004 .
327.Sh HISTORY
328Full support for
329.Tn POSIX
330signal information first appeared in
331.Fx 7.0 .
332The codes
333.Dv SI_USER
334and
335.Dv SI_KERNEL
336can be generated as of
337.Fx 8.1 .
338The code
339.Dv SI_LWP
340can be generated as of
341.Fx 9.0 .
342.Sh AUTHORS
343This manual page was written by
344.An David Xu Aq Mt davidxu@FreeBSD.org .
345