xref: /freebsd/share/man/man3/siginfo.3 (revision c93042724e8df8702b9f5614299d536d13c8e246)
122fc8362SDavid Xu.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
222fc8362SDavid Xu.\" All rights reserved.
322fc8362SDavid Xu.\"
422fc8362SDavid Xu.\" Redistribution and use in source and binary forms, with or without
522fc8362SDavid Xu.\" modification, are permitted provided that the following conditions
622fc8362SDavid Xu.\" are met:
722fc8362SDavid Xu.\" 1. Redistributions of source code must retain the above copyright
822fc8362SDavid Xu.\"    notice(s), this list of conditions and the following disclaimer as
922fc8362SDavid Xu.\"    the first lines of this file unmodified other than the possible
1022fc8362SDavid Xu.\"    addition of one or more copyright notices.
1122fc8362SDavid Xu.\" 2. Redistributions in binary form must reproduce the above copyright
1222fc8362SDavid Xu.\"    notice(s), this list of conditions and the following disclaimer in
1322fc8362SDavid Xu.\"    the documentation and/or other materials provided with the
1422fc8362SDavid Xu.\"    distribution.
1522fc8362SDavid Xu.\"
1622fc8362SDavid Xu.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
1722fc8362SDavid Xu.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1822fc8362SDavid Xu.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1922fc8362SDavid Xu.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
2022fc8362SDavid Xu.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
2122fc8362SDavid Xu.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
2222fc8362SDavid Xu.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
2322fc8362SDavid Xu.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
2422fc8362SDavid Xu.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
2522fc8362SDavid Xu.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
2622fc8362SDavid Xu.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2722fc8362SDavid Xu.\"
2822fc8362SDavid Xu.\" $FreeBSD$
2922fc8362SDavid Xu.\"
30*c9304272SJohn Baldwin.Dd July 14, 2016
3122fc8362SDavid Xu.Dt SIGINFO 3
3222fc8362SDavid Xu.Os
3322fc8362SDavid Xu.Sh NAME
3422fc8362SDavid Xu.Nm siginfo
3522fc8362SDavid Xu.Nd "signal generation information"
3622fc8362SDavid Xu.Sh SYNOPSIS
3722fc8362SDavid Xu.In signal.h
3822fc8362SDavid Xu.Sh DESCRIPTION
3922fc8362SDavid XuA process may request signal information when it is catching a signal.
4022fc8362SDavid XuThe information specifies why the system generated that signal.
4122fc8362SDavid XuTo request signal information in a signal handler, the user can set
4222fc8362SDavid Xu.Dv SA_SIGINFO
4322fc8362SDavid Xuin
4422fc8362SDavid Xu.Va sa_flags
4522fc8362SDavid Xubefore
4622fc8362SDavid Xu.Xr sigaction 2
4722fc8362SDavid Xuis called,
4822fc8362SDavid Xuotherwise the user can use
4922fc8362SDavid Xu.Xr sigwaitinfo 2
5022fc8362SDavid Xuand
5122fc8362SDavid Xu.Xr sigtimedwait 2
5222fc8362SDavid Xuto get signal information.
5322fc8362SDavid XuIn either case, the system returns the information in a structure of type
5422fc8362SDavid Xu.Vt siginfo_t ,
5522fc8362SDavid Xuwhich includes the following information:
5622fc8362SDavid Xu.Bl -column ".Vt union signal" ".Va si_overrun"
57*c9304272SJohn Baldwin.It Sy Type Ta Sy Member Ta Sy Description
5822fc8362SDavid Xu.It Vt int Ta Va si_signo Ta
5922fc8362SDavid Xusignal number
6022fc8362SDavid Xu.It Vt int Ta Va si_errno Ta
6122fc8362SDavid Xuerror number
6222fc8362SDavid Xu.It Vt int Ta Va si_code Ta
6322fc8362SDavid Xusignal code
6422fc8362SDavid Xu.It Vt union sigval Ta Va si_value Ta
6522fc8362SDavid Xusignal value
6622fc8362SDavid Xu.It Vt pid_t Ta Va si_pid Ta
6722fc8362SDavid Xusending process ID
6822fc8362SDavid Xu.It Vt uid_t Ta Va si_uid Ta
6922fc8362SDavid Xusending process's real user ID
7022fc8362SDavid Xu.It Vt void Ta Va *si_addr Ta
7122fc8362SDavid Xuaddress of faulting instruction
7222fc8362SDavid Xu.It Vt int Ta Va si_status Ta
7322fc8362SDavid Xuexit value or signal
7422fc8362SDavid Xu.It Vt long Ta Va si_band Ta
7522fc8362SDavid Xuband event for
7622fc8362SDavid Xu.Dv SIGPOLL
7722fc8362SDavid Xu.It Vt int Ta Va si_trapno Ta
7822fc8362SDavid Xumachine trap code
7922fc8362SDavid Xu.It Vt int Ta Va si_timerid Ta
8022fc8362SDavid Xu.Tn POSIX
8122fc8362SDavid Xutimer ID
8222fc8362SDavid Xu.It Vt int Ta Va si_overrun Ta
8322fc8362SDavid Xu.Tn POSIX
8422fc8362SDavid Xutimer overrun count
8522fc8362SDavid Xu.It Vt int Ta Va si_mqd Ta
8622fc8362SDavid Xu.Tn POSIX
8722fc8362SDavid Xumessage queue ID
8822fc8362SDavid Xu.El
8922fc8362SDavid Xu.Pp
9022fc8362SDavid XuThe
9122fc8362SDavid Xu.Va si_signo
9222fc8362SDavid Xumember contains the signal number.
9322fc8362SDavid Xu.Pp
9422fc8362SDavid XuThe
9522fc8362SDavid Xu.Va si_errno
9622fc8362SDavid Xumember contains an error number defined in the file
9722fc8362SDavid Xu.In errno.h .
9822fc8362SDavid Xu.Pp
9922fc8362SDavid XuThe
10022fc8362SDavid Xu.Va si_code
10122fc8362SDavid Xumember contains a code which describes the cause of the signal.
10222fc8362SDavid XuThe macros specified in the
10385213a80SRuslan Ermilov.Sy Code
10422fc8362SDavid Xucolumn of the following table are defined
10522fc8362SDavid Xufor use as values of
10622fc8362SDavid Xu.Va si_code
10722fc8362SDavid Xuthat are signal-specific or non-signal-specific reasons why the signal was
10822fc8362SDavid Xugenerated:
10922fc8362SDavid Xu.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
110*c9304272SJohn Baldwin.It Sy Signal Ta Sy Code Ta Sy Reason
11122fc8362SDavid Xu.It Dv SIGILL Ta Dv ILL_ILLOPC Ta
11222fc8362SDavid Xuillegal opcode
11322fc8362SDavid Xu.It Ta Dv ILL_ILLOPN Ta
11422fc8362SDavid Xuillegal operand
11522fc8362SDavid Xu.It Ta Dv ILL_ILLADR Ta
11622fc8362SDavid Xuillegal addressing mode
11722fc8362SDavid Xu.It Ta Dv ILL_ILLTRP Ta
11822fc8362SDavid Xuillegal trap
11922fc8362SDavid Xu.It Ta Dv ILL_PRVOPC Ta
120dbcf945aSDavid Xuillegal privileged opcode
12122fc8362SDavid Xu.It Ta Dv ILL_PRVREG Ta
122dbcf945aSDavid Xuillegal privileged register
12322fc8362SDavid Xu.It Ta Dv ILL_COPROC Ta
12422fc8362SDavid Xucoprocessor error
12522fc8362SDavid Xu.It Ta Dv ILL_BADSTK Ta
12622fc8362SDavid Xuinternal stack error
12722fc8362SDavid Xu.It Dv SIGFPE Ta Dv FPE_INTDIV Ta
12822fc8362SDavid Xuinteger divide by zero
12922fc8362SDavid Xu.It Ta Dv FPE_INTOVF Ta
13022fc8362SDavid Xuinteger overflow
13122fc8362SDavid Xu.It Ta Dv FPE_FLTDIV Ta
13222fc8362SDavid Xufloating-point divide by zero
13322fc8362SDavid Xu.It Ta Dv FPE_FLTOVF Ta
13422fc8362SDavid Xufloating-point overflow
13522fc8362SDavid Xu.It Ta Dv FPE_FLTUND Ta
13622fc8362SDavid Xufloating-point underflow
13722fc8362SDavid Xu.It Ta Dv FPE_FLTRES Ta
13822fc8362SDavid Xufloating-point inexact result
13922fc8362SDavid Xu.It Ta Dv FPE_FLTINV Ta
14022fc8362SDavid Xuinvalid floating-point operation
14122fc8362SDavid Xu.It Ta Dv FPE_FLTSUB Ta
14222fc8362SDavid Xusubscript out of range
14322fc8362SDavid Xu.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta
14422fc8362SDavid Xuaddress not mapped to object
14522fc8362SDavid Xu.It Ta Dv SEGV_ACCERR Ta
14622fc8362SDavid Xuinvalid permissions for mapped object
14722fc8362SDavid Xu.It Dv SIGBUS Ta Dv BUS_ADRALN Ta
14822fc8362SDavid Xuinvalid address alignment
14922fc8362SDavid Xu.It Ta Dv BUS_ADRERR Ta
15022fc8362SDavid Xunonexistent physical address
15122fc8362SDavid Xu.It Ta Dv BUS_OBJERR Ta
15222fc8362SDavid Xuobject-specific hardware error
15322fc8362SDavid Xu.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
15422fc8362SDavid Xuprocess breakpoint
15522fc8362SDavid Xu.It Ta Dv TRAP_TRACE Ta
15622fc8362SDavid Xuprocess trace trap
1574ca2a3f7SJilles Tjoelker.It Ta Dv TRAP_DTRACE Ta
1584ca2a3f7SJilles TjoelkerDTrace induced trap
15922fc8362SDavid Xu.It Dv SIGCHLD Ta Dv CLD_EXITED Ta
16022fc8362SDavid Xuchild has exited
16122fc8362SDavid Xu.It Ta Dv CLD_KILLED Ta
16222fc8362SDavid Xuchild has terminated abnormally and did not create a core file
16322fc8362SDavid Xu.It Ta Dv CLD_DUMPED Ta
16422fc8362SDavid Xuchild has terminated abnormally and created a core file
16522fc8362SDavid Xu.It Ta Dv CLD_TRAPPED Ta
16622fc8362SDavid Xutraced child has trapped
16722fc8362SDavid Xu.It Ta Dv CLD_STOPPED Ta
16822fc8362SDavid Xuchild has stopped
16922fc8362SDavid Xu.It Ta Dv CLD_CONTINUED Ta
17022fc8362SDavid Xustopped child has continued
17122fc8362SDavid Xu.It Dv SIGPOLL Ta Dv POLL_IN Ta
17222fc8362SDavid Xudata input available
17322fc8362SDavid Xu.It Ta Dv POLL_OUT Ta
17422fc8362SDavid Xuoutput buffers available
17522fc8362SDavid Xu.It Ta Dv POLL_MSG Ta
17622fc8362SDavid Xuinput message available
17722fc8362SDavid Xu.It Ta Dv POLL_ERR Ta
17822fc8362SDavid XuI/O error
17922fc8362SDavid Xu.It Ta Dv POLL_PRI Ta
18022fc8362SDavid Xuhigh priority input available
18122fc8362SDavid Xu.It Ta Dv POLL_HUP Ta
18222fc8362SDavid Xudevice disconnected
18322fc8362SDavid Xu.It Any Ta Dv SI_NOINFO Ta
18422fc8362SDavid XuOnly the
18522fc8362SDavid Xu.Va si_signo
18622fc8362SDavid Xumember is meaningful; the value of all other members is unspecified.
18722fc8362SDavid Xu.It Ta Dv SI_USER Ta
18822fc8362SDavid Xusignal sent by
18922fc8362SDavid Xu.Xr kill 2
19022fc8362SDavid Xu.It Ta Dv SI_QUEUE Ta
19122fc8362SDavid Xusignal sent by
19222fc8362SDavid Xu.Xr sigqueue 2
19322fc8362SDavid Xu.It Ta Dv SI_TIMER Ta
19422fc8362SDavid Xusignal generated by expiration of a timer set by
19522fc8362SDavid Xu.Xr timer_settime 2
19622fc8362SDavid Xu.It Ta Dv SI_ASYNCIO Ta
19722fc8362SDavid Xusignal generated by completion of an asynchronous I/O request
19822fc8362SDavid Xu.It Ta Dv SI_MESGQ Ta
19922fc8362SDavid Xusignal generated by arrival of a message on an empty message queue
200a4c22c27SJilles Tjoelker.It Ta Dv SI_KERNEL Ta
201a4c22c27SJilles Tjoelkersignal generated by miscellaneous parts of the kernel
2025437c0d6SJilles Tjoelker.It Ta Dv SI_LWP Ta
2035437c0d6SJilles Tjoelkersignal sent by
2045437c0d6SJilles Tjoelker.Xr pthread_kill 3
20522fc8362SDavid Xu.El
20622fc8362SDavid Xu.Pp
20722fc8362SDavid XuIn addition, the following signal-specific information is available:
20822fc8362SDavid Xu.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
209*c9304272SJohn Baldwin.It Sy Signal Ta Sy Member Ta Sy Value
21022fc8362SDavid Xu.It Dv SIGILL Ta Va si_addr Ta
21122fc8362SDavid Xuaddress of faulting instruction
21222fc8362SDavid Xu.It Ta Va si_trapno Ta
21322fc8362SDavid Xumachine dependent of trap code
21422fc8362SDavid Xu.It Dv SIGFPE Ta Va si_addr Ta
21522fc8362SDavid Xuaddress of faulting instruction
21622fc8362SDavid Xu.It Ta Va si_trapno Ta
21722fc8362SDavid Xumachine dependent of trap code
21822fc8362SDavid Xu.It Dv SIGSEGV Ta Va si_addr Ta
21922fc8362SDavid Xuaddress of faulting memory reference
22022fc8362SDavid Xu.It Ta Va si_trapno Ta
22122fc8362SDavid Xumachine dependent of trap code
22222fc8362SDavid Xu.It Dv SIGBUS Ta Va si_addr Ta
22322fc8362SDavid Xuaddress of faulting instruction
22422fc8362SDavid Xu.It Ta Va si_trapno Ta
22522fc8362SDavid Xumachine dependent of trap code
226b6514098SUlrich Spörlein.It Dv SIGCHLD Ta Va si_pid Ta
22722fc8362SDavid Xuchild process ID
22822fc8362SDavid Xu.It Ta Va si_status Ta
22985213a80SRuslan Ermilovexit value or signal; if
23022fc8362SDavid Xu.Va si_code
23122fc8362SDavid Xuis equal to
23222fc8362SDavid Xu.Dv CLD_EXITED ,
23322fc8362SDavid Xuthen it is equal to the exit value of the child process, otherwise,
23422fc8362SDavid Xuit is equal to a signal that caused the child process to change state.
23522fc8362SDavid Xu.It Ta Va si_uid Ta "real user ID of the process that sent the signal"
23622fc8362SDavid Xu.It Dv SIGPOLL Ta Va si_band Ta "band event for"
23722fc8362SDavid Xu.Dv POLL_IN , POLL_OUT ,
23822fc8362SDavid Xuor
23922fc8362SDavid Xu.Dv POLL_MSG
24022fc8362SDavid Xu.El
24122fc8362SDavid Xu.Pp
24222fc8362SDavid XuFinally, the following code-specific information is available:
243*c9304272SJohn Baldwin.Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun"
244*c9304272SJohn Baldwin.It Sy Code Ta Sy Member Ta Sy Value
245a4c22c27SJilles Tjoelker.It Dv SI_USER Ta Va si_pid Ta
246a4c22c27SJilles Tjoelkerthe process ID that sent the signal
247a4c22c27SJilles Tjoelker.It Ta Va si_uid Ta
248a4c22c27SJilles Tjoelkerreal user ID of the process that sent the signal
24922fc8362SDavid Xu.It Dv SI_QUEUE Ta Va si_value Ta
25022fc8362SDavid Xuthe value passed to
25122fc8362SDavid Xu.Xr sigqueue 2
25222fc8362SDavid Xusystem call
25322fc8362SDavid Xu.It Ta Va si_pid Ta
25422fc8362SDavid Xuthe process ID that sent the signal
25522fc8362SDavid Xu.It Ta Va si_uid Ta
25622fc8362SDavid Xureal user ID of the process that sent the signal
25722fc8362SDavid Xu.It Dv SI_TIMER Ta Va si_value Ta
25822fc8362SDavid Xuthe value passed to
25922fc8362SDavid Xu.Xr timer_create 2
26022fc8362SDavid Xusystem call
26122fc8362SDavid Xu.It Ta Va si_timerid Ta
26222fc8362SDavid Xuthe timer ID returned by
26322fc8362SDavid Xu.Xr timer_create 2
26422fc8362SDavid Xusystem call
26522fc8362SDavid Xu.It Ta Va si_overrun Ta
26622fc8362SDavid Xutimer overrun count corresponding to the signal
26722fc8362SDavid Xu.It Ta Va si_errno Ta
26822fc8362SDavid XuIf timer overrun will be
26922fc8362SDavid Xu.Brq Dv DELAYTIMER_MAX ,
27022fc8362SDavid Xuan error code defined in
27122fc8362SDavid Xu.In errno.h
27222fc8362SDavid Xuis set
27322fc8362SDavid Xu.It Dv SI_ASYNCIO Ta Va si_value Ta
27422fc8362SDavid Xuthe value passed to aio system calls
27522fc8362SDavid Xu.It Dv SI_MESGQ Ta Va si_value Ta
27622fc8362SDavid Xuthe value passed to
27722fc8362SDavid Xu.Xr mq_notify 2
27822fc8362SDavid Xusystem call
27922fc8362SDavid Xu.It Ta Va si_mqd Ta
28022fc8362SDavid Xuthe ID of the message queue which generated the signal
2815437c0d6SJilles Tjoelker.It Dv SI_LWP Ta Va si_pid Ta
2825437c0d6SJilles Tjoelkerthe process ID that sent the signal
2835437c0d6SJilles Tjoelker.It Ta Va si_uid Ta
2845437c0d6SJilles Tjoelkerreal user ID of the process that sent the signal
28522fc8362SDavid Xu.El
28622fc8362SDavid Xu.Sh NOTES
28785213a80SRuslan ErmilovCurrently, the kernel never generates the
288dbcf945aSDavid Xu.Dv SIGPOLL
289dbcf945aSDavid Xusignal.
29022fc8362SDavid Xu.Dv SIGCHLD
291dbcf945aSDavid Xusignal is queued when a process changed its status or exited.
29222fc8362SDavid Xu.Tn POSIX
29385213a80SRuslan ErmilovRealtime Extensions like aio, timer, and message queue also queue
29422fc8362SDavid Xusignals.
295a4c22c27SJilles TjoelkerSignals with code
2965437c0d6SJilles Tjoelker.Dv SI_USER ,
297a4c22c27SJilles Tjoelker.Dv SI_KERNEL
2985437c0d6SJilles Tjoelkeror
2995437c0d6SJilles Tjoelker.Dv SI_LWP
300a4c22c27SJilles Tjoelkerare only queued if there are sufficient resources;
301a4c22c27SJilles Tjoelkerotherwise,
302a4c22c27SJilles Tjoelker.Dv SI_NOINFO
303a4c22c27SJilles Tjoelkerresults.
30422fc8362SDavid XuFor some hardware architectures, the exact value of
30522fc8362SDavid Xu.Va si_addr
30622fc8362SDavid Xumight not be available.
30722fc8362SDavid Xu.Sh SEE ALSO
30822fc8362SDavid Xu.Xr aio_read 2 ,
30922fc8362SDavid Xu.Xr kill 2 ,
31022fc8362SDavid Xu.Xr mq_notify 2 ,
31122fc8362SDavid Xu.Xr sigaction 2 ,
31222fc8362SDavid Xu.Xr sigqueue 2 ,
31322fc8362SDavid Xu.Xr sigwaitinfo 2 ,
31422fc8362SDavid Xu.Xr timer_create 2 ,
31522fc8362SDavid Xu.Xr timer_settime 2 ,
316a4c22c27SJilles Tjoelker.Xr waitpid 2 ,
317a4c22c27SJilles Tjoelker.Xr pthread_kill 3
31822fc8362SDavid Xu.Sh STANDARDS
31922fc8362SDavid XuThe
32022fc8362SDavid Xu.Vt siginfo_t
32122fc8362SDavid Xutype conforms to
32222fc8362SDavid Xu.St -p1003.1-2004 .
32322fc8362SDavid Xu.Sh HISTORY
32422fc8362SDavid XuFull support for
32522fc8362SDavid Xu.Tn POSIX
32622fc8362SDavid Xusignal information first appeared in
32722fc8362SDavid Xu.Fx 7.0 .
328a4c22c27SJilles TjoelkerThe codes
329a4c22c27SJilles Tjoelker.Dv SI_USER
330a4c22c27SJilles Tjoelkerand
331a4c22c27SJilles Tjoelker.Dv SI_KERNEL
332a4c22c27SJilles Tjoelkercan be generated as of
333a4c22c27SJilles Tjoelker.Fx 8.1 .
3345437c0d6SJilles TjoelkerThe code
3355437c0d6SJilles Tjoelker.Dv SI_LWP
3365437c0d6SJilles Tjoelkercan be generated as of
3375437c0d6SJilles Tjoelker.Fx 9.0 .
33822fc8362SDavid Xu.Sh AUTHORS
33922fc8362SDavid XuThis manual page was written by
340a63d6c94SBaptiste Daroussin.An David Xu Aq Mt davidxu@FreeBSD.org .
341