xref: /freebsd/share/man/man3/siginfo.3 (revision c81f8aa528af4f568088080bbf4bccbc6a593b29)
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*c81f8aa5SJohn Baldwin.Dd April 24, 2018
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"
57c9304272SJohn 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"
110c9304272SJohn 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
159*c81f8aa5SJohn Baldwin.It Ta Dv TRAP_CAP Ta
160*c81f8aa5SJohn Baldwincapabilities protective trap
16122fc8362SDavid Xu.It Dv SIGCHLD Ta Dv CLD_EXITED Ta
16222fc8362SDavid Xuchild has exited
16322fc8362SDavid Xu.It Ta Dv CLD_KILLED Ta
16422fc8362SDavid Xuchild has terminated abnormally and did not create a core file
16522fc8362SDavid Xu.It Ta Dv CLD_DUMPED Ta
16622fc8362SDavid Xuchild has terminated abnormally and created a core file
16722fc8362SDavid Xu.It Ta Dv CLD_TRAPPED Ta
16822fc8362SDavid Xutraced child has trapped
16922fc8362SDavid Xu.It Ta Dv CLD_STOPPED Ta
17022fc8362SDavid Xuchild has stopped
17122fc8362SDavid Xu.It Ta Dv CLD_CONTINUED Ta
17222fc8362SDavid Xustopped child has continued
17322fc8362SDavid Xu.It Dv SIGPOLL Ta Dv POLL_IN Ta
17422fc8362SDavid Xudata input available
17522fc8362SDavid Xu.It Ta Dv POLL_OUT Ta
17622fc8362SDavid Xuoutput buffers available
17722fc8362SDavid Xu.It Ta Dv POLL_MSG Ta
17822fc8362SDavid Xuinput message available
17922fc8362SDavid Xu.It Ta Dv POLL_ERR Ta
18022fc8362SDavid XuI/O error
18122fc8362SDavid Xu.It Ta Dv POLL_PRI Ta
18222fc8362SDavid Xuhigh priority input available
18322fc8362SDavid Xu.It Ta Dv POLL_HUP Ta
18422fc8362SDavid Xudevice disconnected
18522fc8362SDavid Xu.It Any Ta Dv SI_NOINFO Ta
18622fc8362SDavid XuOnly the
18722fc8362SDavid Xu.Va si_signo
18822fc8362SDavid Xumember is meaningful; the value of all other members is unspecified.
18922fc8362SDavid Xu.It Ta Dv SI_USER Ta
19022fc8362SDavid Xusignal sent by
19122fc8362SDavid Xu.Xr kill 2
19222fc8362SDavid Xu.It Ta Dv SI_QUEUE Ta
19322fc8362SDavid Xusignal sent by
19422fc8362SDavid Xu.Xr sigqueue 2
19522fc8362SDavid Xu.It Ta Dv SI_TIMER Ta
19622fc8362SDavid Xusignal generated by expiration of a timer set by
19722fc8362SDavid Xu.Xr timer_settime 2
19822fc8362SDavid Xu.It Ta Dv SI_ASYNCIO Ta
19922fc8362SDavid Xusignal generated by completion of an asynchronous I/O request
20022fc8362SDavid Xu.It Ta Dv SI_MESGQ Ta
20122fc8362SDavid Xusignal generated by arrival of a message on an empty message queue
202a4c22c27SJilles Tjoelker.It Ta Dv SI_KERNEL Ta
203a4c22c27SJilles Tjoelkersignal generated by miscellaneous parts of the kernel
2045437c0d6SJilles Tjoelker.It Ta Dv SI_LWP Ta
2055437c0d6SJilles Tjoelkersignal sent by
2065437c0d6SJilles Tjoelker.Xr pthread_kill 3
20722fc8362SDavid Xu.El
20822fc8362SDavid Xu.Pp
20922fc8362SDavid XuIn addition, the following signal-specific information is available:
21022fc8362SDavid Xu.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
211c9304272SJohn Baldwin.It Sy Signal Ta Sy Member Ta Sy Value
21222fc8362SDavid Xu.It Dv SIGILL Ta Va si_addr Ta
21322fc8362SDavid Xuaddress of faulting instruction
21422fc8362SDavid Xu.It Ta Va si_trapno Ta
21522fc8362SDavid Xumachine dependent of trap code
21622fc8362SDavid Xu.It Dv SIGFPE Ta Va si_addr Ta
21722fc8362SDavid Xuaddress of faulting instruction
21822fc8362SDavid Xu.It Ta Va si_trapno Ta
21922fc8362SDavid Xumachine dependent of trap code
22022fc8362SDavid Xu.It Dv SIGSEGV Ta Va si_addr Ta
22122fc8362SDavid Xuaddress of faulting memory reference
22222fc8362SDavid Xu.It Ta Va si_trapno Ta
22322fc8362SDavid Xumachine dependent of trap code
22422fc8362SDavid Xu.It Dv SIGBUS Ta Va si_addr Ta
22522fc8362SDavid Xuaddress of faulting instruction
22622fc8362SDavid Xu.It Ta Va si_trapno Ta
22722fc8362SDavid Xumachine dependent of trap code
228b6514098SUlrich Spörlein.It Dv SIGCHLD Ta Va si_pid Ta
22922fc8362SDavid Xuchild process ID
23022fc8362SDavid Xu.It Ta Va si_status Ta
23185213a80SRuslan Ermilovexit value or signal; if
23222fc8362SDavid Xu.Va si_code
23322fc8362SDavid Xuis equal to
23422fc8362SDavid Xu.Dv CLD_EXITED ,
23522fc8362SDavid Xuthen it is equal to the exit value of the child process, otherwise,
23622fc8362SDavid Xuit is equal to a signal that caused the child process to change state.
23722fc8362SDavid Xu.It Ta Va si_uid Ta "real user ID of the process that sent the signal"
23822fc8362SDavid Xu.It Dv SIGPOLL Ta Va si_band Ta "band event for"
23922fc8362SDavid Xu.Dv POLL_IN , POLL_OUT ,
24022fc8362SDavid Xuor
24122fc8362SDavid Xu.Dv POLL_MSG
24222fc8362SDavid Xu.El
24322fc8362SDavid Xu.Pp
24422fc8362SDavid XuFinally, the following code-specific information is available:
245c9304272SJohn Baldwin.Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun"
246c9304272SJohn Baldwin.It Sy Code Ta Sy Member Ta Sy Value
247a4c22c27SJilles Tjoelker.It Dv SI_USER Ta Va si_pid Ta
248a4c22c27SJilles Tjoelkerthe process ID that sent the signal
249a4c22c27SJilles Tjoelker.It Ta Va si_uid Ta
250a4c22c27SJilles Tjoelkerreal user ID of the process that sent the signal
25122fc8362SDavid Xu.It Dv SI_QUEUE Ta Va si_value Ta
25222fc8362SDavid Xuthe value passed to
25322fc8362SDavid Xu.Xr sigqueue 2
25422fc8362SDavid Xusystem call
25522fc8362SDavid Xu.It Ta Va si_pid Ta
25622fc8362SDavid Xuthe process ID that sent the signal
25722fc8362SDavid Xu.It Ta Va si_uid Ta
25822fc8362SDavid Xureal user ID of the process that sent the signal
25922fc8362SDavid Xu.It Dv SI_TIMER Ta Va si_value Ta
26022fc8362SDavid Xuthe value passed to
26122fc8362SDavid Xu.Xr timer_create 2
26222fc8362SDavid Xusystem call
26322fc8362SDavid Xu.It Ta Va si_timerid Ta
26422fc8362SDavid Xuthe timer ID returned by
26522fc8362SDavid Xu.Xr timer_create 2
26622fc8362SDavid Xusystem call
26722fc8362SDavid Xu.It Ta Va si_overrun Ta
26822fc8362SDavid Xutimer overrun count corresponding to the signal
26922fc8362SDavid Xu.It Ta Va si_errno Ta
27022fc8362SDavid XuIf timer overrun will be
27122fc8362SDavid Xu.Brq Dv DELAYTIMER_MAX ,
27222fc8362SDavid Xuan error code defined in
27322fc8362SDavid Xu.In errno.h
27422fc8362SDavid Xuis set
27522fc8362SDavid Xu.It Dv SI_ASYNCIO Ta Va si_value Ta
27622fc8362SDavid Xuthe value passed to aio system calls
27722fc8362SDavid Xu.It Dv SI_MESGQ Ta Va si_value Ta
27822fc8362SDavid Xuthe value passed to
27922fc8362SDavid Xu.Xr mq_notify 2
28022fc8362SDavid Xusystem call
28122fc8362SDavid Xu.It Ta Va si_mqd Ta
28222fc8362SDavid Xuthe ID of the message queue which generated the signal
2835437c0d6SJilles Tjoelker.It Dv SI_LWP Ta Va si_pid Ta
2845437c0d6SJilles Tjoelkerthe process ID that sent the signal
2855437c0d6SJilles Tjoelker.It Ta Va si_uid Ta
2865437c0d6SJilles Tjoelkerreal user ID of the process that sent the signal
28722fc8362SDavid Xu.El
28822fc8362SDavid Xu.Sh NOTES
28985213a80SRuslan ErmilovCurrently, the kernel never generates the
290dbcf945aSDavid Xu.Dv SIGPOLL
291dbcf945aSDavid Xusignal.
29222fc8362SDavid Xu.Dv SIGCHLD
293dbcf945aSDavid Xusignal is queued when a process changed its status or exited.
29422fc8362SDavid Xu.Tn POSIX
29585213a80SRuslan ErmilovRealtime Extensions like aio, timer, and message queue also queue
29622fc8362SDavid Xusignals.
297a4c22c27SJilles TjoelkerSignals with code
2985437c0d6SJilles Tjoelker.Dv SI_USER ,
299a4c22c27SJilles Tjoelker.Dv SI_KERNEL
3005437c0d6SJilles Tjoelkeror
3015437c0d6SJilles Tjoelker.Dv SI_LWP
302a4c22c27SJilles Tjoelkerare only queued if there are sufficient resources;
303a4c22c27SJilles Tjoelkerotherwise,
304a4c22c27SJilles Tjoelker.Dv SI_NOINFO
305a4c22c27SJilles Tjoelkerresults.
30622fc8362SDavid XuFor some hardware architectures, the exact value of
30722fc8362SDavid Xu.Va si_addr
30822fc8362SDavid Xumight not be available.
30922fc8362SDavid Xu.Sh SEE ALSO
31022fc8362SDavid Xu.Xr aio_read 2 ,
31122fc8362SDavid Xu.Xr kill 2 ,
31222fc8362SDavid Xu.Xr mq_notify 2 ,
31322fc8362SDavid Xu.Xr sigaction 2 ,
31422fc8362SDavid Xu.Xr sigqueue 2 ,
31522fc8362SDavid Xu.Xr sigwaitinfo 2 ,
31622fc8362SDavid Xu.Xr timer_create 2 ,
31722fc8362SDavid Xu.Xr timer_settime 2 ,
318a4c22c27SJilles Tjoelker.Xr waitpid 2 ,
319a4c22c27SJilles Tjoelker.Xr pthread_kill 3
32022fc8362SDavid Xu.Sh STANDARDS
32122fc8362SDavid XuThe
32222fc8362SDavid Xu.Vt siginfo_t
32322fc8362SDavid Xutype conforms to
32422fc8362SDavid Xu.St -p1003.1-2004 .
32522fc8362SDavid Xu.Sh HISTORY
32622fc8362SDavid XuFull support for
32722fc8362SDavid Xu.Tn POSIX
32822fc8362SDavid Xusignal information first appeared in
32922fc8362SDavid Xu.Fx 7.0 .
330a4c22c27SJilles TjoelkerThe codes
331a4c22c27SJilles Tjoelker.Dv SI_USER
332a4c22c27SJilles Tjoelkerand
333a4c22c27SJilles Tjoelker.Dv SI_KERNEL
334a4c22c27SJilles Tjoelkercan be generated as of
335a4c22c27SJilles Tjoelker.Fx 8.1 .
3365437c0d6SJilles TjoelkerThe code
3375437c0d6SJilles Tjoelker.Dv SI_LWP
3385437c0d6SJilles Tjoelkercan be generated as of
3395437c0d6SJilles Tjoelker.Fx 9.0 .
34022fc8362SDavid Xu.Sh AUTHORS
34122fc8362SDavid XuThis manual page was written by
342a63d6c94SBaptiste Daroussin.An David Xu Aq Mt davidxu@FreeBSD.org .
343