/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 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 davidxu@FreeBSD.org .