xref: /freebsd/share/man/man3/siginfo.3 (revision cf98bc28d39d6df5386ac57375af1b60af5d6bb3)
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.\"
30bd012c71SMitchell Horne.Dd February 17, 2021
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
71b027b663SJohn Baldwinvirtual address
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
88*cf98bc28SDavid Chisnall.It Vt int Ta Va si_syscall Ta
89*cf98bc28SDavid Chisnallsystem-call number for system calls blocked by Capsicum
9022fc8362SDavid Xu.El
9122fc8362SDavid Xu.Pp
9222fc8362SDavid XuThe
9322fc8362SDavid Xu.Va si_signo
9422fc8362SDavid Xumember contains the signal number.
9522fc8362SDavid Xu.Pp
9622fc8362SDavid XuThe
9722fc8362SDavid Xu.Va si_errno
9822fc8362SDavid Xumember contains an error number defined in the file
9922fc8362SDavid Xu.In errno.h .
10022fc8362SDavid Xu.Pp
10122fc8362SDavid XuThe
10222fc8362SDavid Xu.Va si_code
10322fc8362SDavid Xumember contains a code which describes the cause of the signal.
10422fc8362SDavid XuThe macros specified in the
10585213a80SRuslan Ermilov.Sy Code
10622fc8362SDavid Xucolumn of the following table are defined
10722fc8362SDavid Xufor use as values of
10822fc8362SDavid Xu.Va si_code
10922fc8362SDavid Xuthat are signal-specific or non-signal-specific reasons why the signal was
11022fc8362SDavid Xugenerated:
11122fc8362SDavid Xu.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
112c9304272SJohn Baldwin.It Sy Signal Ta Sy Code Ta Sy Reason
11322fc8362SDavid Xu.It Dv SIGILL Ta Dv ILL_ILLOPC Ta
11422fc8362SDavid Xuillegal opcode
11522fc8362SDavid Xu.It Ta Dv ILL_ILLOPN Ta
11622fc8362SDavid Xuillegal operand
11722fc8362SDavid Xu.It Ta Dv ILL_ILLADR Ta
11822fc8362SDavid Xuillegal addressing mode
11922fc8362SDavid Xu.It Ta Dv ILL_ILLTRP Ta
12022fc8362SDavid Xuillegal trap
12122fc8362SDavid Xu.It Ta Dv ILL_PRVOPC Ta
122dbcf945aSDavid Xuillegal privileged opcode
12322fc8362SDavid Xu.It Ta Dv ILL_PRVREG Ta
124dbcf945aSDavid Xuillegal privileged register
12522fc8362SDavid Xu.It Ta Dv ILL_COPROC Ta
12622fc8362SDavid Xucoprocessor error
12722fc8362SDavid Xu.It Ta Dv ILL_BADSTK Ta
12822fc8362SDavid Xuinternal stack error
12922fc8362SDavid Xu.It Dv SIGFPE Ta Dv FPE_INTDIV Ta
13022fc8362SDavid Xuinteger divide by zero
13122fc8362SDavid Xu.It Ta Dv FPE_INTOVF Ta
13222fc8362SDavid Xuinteger overflow
13322fc8362SDavid Xu.It Ta Dv FPE_FLTDIV Ta
13422fc8362SDavid Xufloating-point divide by zero
13522fc8362SDavid Xu.It Ta Dv FPE_FLTOVF Ta
13622fc8362SDavid Xufloating-point overflow
13722fc8362SDavid Xu.It Ta Dv FPE_FLTUND Ta
13822fc8362SDavid Xufloating-point underflow
13922fc8362SDavid Xu.It Ta Dv FPE_FLTRES Ta
14022fc8362SDavid Xufloating-point inexact result
14122fc8362SDavid Xu.It Ta Dv FPE_FLTINV Ta
14222fc8362SDavid Xuinvalid floating-point operation
14322fc8362SDavid Xu.It Ta Dv FPE_FLTSUB Ta
14422fc8362SDavid Xusubscript out of range
14522fc8362SDavid Xu.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta
14622fc8362SDavid Xuaddress not mapped to object
14722fc8362SDavid Xu.It Ta Dv SEGV_ACCERR Ta
14822fc8362SDavid Xuinvalid permissions for mapped object
14922fc8362SDavid Xu.It Dv SIGBUS Ta Dv BUS_ADRALN Ta
15022fc8362SDavid Xuinvalid address alignment
15122fc8362SDavid Xu.It Ta Dv BUS_ADRERR Ta
15222fc8362SDavid Xunonexistent physical address
15322fc8362SDavid Xu.It Ta Dv BUS_OBJERR Ta
15422fc8362SDavid Xuobject-specific hardware error
1550298cf17SKonstantin Belousov.It Ta Dv BUS_OOMERR Ta
1560298cf17SKonstantin Belousovcannot alloc a page to map at fault
15722fc8362SDavid Xu.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta
15822fc8362SDavid Xuprocess breakpoint
15922fc8362SDavid Xu.It Ta Dv TRAP_TRACE Ta
16022fc8362SDavid Xuprocess trace trap
1614ca2a3f7SJilles Tjoelker.It Ta Dv TRAP_DTRACE Ta
1624ca2a3f7SJilles TjoelkerDTrace induced trap
163c81f8aa5SJohn Baldwin.It Ta Dv TRAP_CAP Ta
164c81f8aa5SJohn Baldwincapabilities protective trap
16522fc8362SDavid Xu.It Dv SIGCHLD Ta Dv CLD_EXITED Ta
16622fc8362SDavid Xuchild has exited
16722fc8362SDavid Xu.It Ta Dv CLD_KILLED Ta
16822fc8362SDavid Xuchild has terminated abnormally and did not create a core file
16922fc8362SDavid Xu.It Ta Dv CLD_DUMPED Ta
17022fc8362SDavid Xuchild has terminated abnormally and created a core file
17122fc8362SDavid Xu.It Ta Dv CLD_TRAPPED Ta
17222fc8362SDavid Xutraced child has trapped
17322fc8362SDavid Xu.It Ta Dv CLD_STOPPED Ta
17422fc8362SDavid Xuchild has stopped
17522fc8362SDavid Xu.It Ta Dv CLD_CONTINUED Ta
17622fc8362SDavid Xustopped child has continued
17722fc8362SDavid Xu.It Dv SIGPOLL Ta Dv POLL_IN Ta
17822fc8362SDavid Xudata input available
17922fc8362SDavid Xu.It Ta Dv POLL_OUT Ta
18022fc8362SDavid Xuoutput buffers available
18122fc8362SDavid Xu.It Ta Dv POLL_MSG Ta
18222fc8362SDavid Xuinput message available
18322fc8362SDavid Xu.It Ta Dv POLL_ERR Ta
18422fc8362SDavid XuI/O error
18522fc8362SDavid Xu.It Ta Dv POLL_PRI Ta
18622fc8362SDavid Xuhigh priority input available
18722fc8362SDavid Xu.It Ta Dv POLL_HUP Ta
18822fc8362SDavid Xudevice disconnected
18922fc8362SDavid Xu.It Any Ta Dv SI_NOINFO Ta
19022fc8362SDavid XuOnly the
19122fc8362SDavid Xu.Va si_signo
19222fc8362SDavid Xumember is meaningful; the value of all other members is unspecified.
19322fc8362SDavid Xu.It Ta Dv SI_USER Ta
19422fc8362SDavid Xusignal sent by
19522fc8362SDavid Xu.Xr kill 2
19622fc8362SDavid Xu.It Ta Dv SI_QUEUE Ta
19722fc8362SDavid Xusignal sent by
19822fc8362SDavid Xu.Xr sigqueue 2
19922fc8362SDavid Xu.It Ta Dv SI_TIMER Ta
20022fc8362SDavid Xusignal generated by expiration of a timer set by
20122fc8362SDavid Xu.Xr timer_settime 2
20222fc8362SDavid Xu.It Ta Dv SI_ASYNCIO Ta
20322fc8362SDavid Xusignal generated by completion of an asynchronous I/O request
20422fc8362SDavid Xu.It Ta Dv SI_MESGQ Ta
20522fc8362SDavid Xusignal generated by arrival of a message on an empty message queue
206a4c22c27SJilles Tjoelker.It Ta Dv SI_KERNEL Ta
207a4c22c27SJilles Tjoelkersignal generated by miscellaneous parts of the kernel
2085437c0d6SJilles Tjoelker.It Ta Dv SI_LWP Ta
2095437c0d6SJilles Tjoelkersignal sent by
2105437c0d6SJilles Tjoelker.Xr pthread_kill 3
21122fc8362SDavid Xu.El
21222fc8362SDavid Xu.Pp
213b027b663SJohn BaldwinFor synchronous signals,
214b027b663SJohn Baldwin.Va si_addr
215b027b663SJohn Baldwinis generally set to the address of the faulting instruction.
216b027b663SJohn BaldwinHowever, synchronous signals raised by a faulting memory access such as
217b027b663SJohn Baldwin.Dv SIGSEGV
218b027b663SJohn Baldwinand
219b027b663SJohn Baldwin.Dv SIGBUS
220b027b663SJohn Baldwinmay report the address of the faulting memory access (if available) in
221b027b663SJohn Baldwin.Va si_addr
222b027b663SJohn Baldwininstead.
223bd012c71SMitchell HorneAdditionally
224bd012c71SMitchell Horne.Dv SIGTRAP
225bd012c71SMitchell Horneraised by a hardware watchpoint exception may report the data address that
226bd012c71SMitchell Hornetriggered the watchpoint in
227bd012c71SMitchell Horne.Va si_addr .
228b027b663SJohn Baldwin.Pp
229b027b663SJohn BaldwinSychronous signals set
230b027b663SJohn Baldwin.Va si_trapno
231b027b663SJohn Baldwinto a machine-dependent trap number.
232b027b663SJohn Baldwin.Pp
23322fc8362SDavid XuIn addition, the following signal-specific information is available:
23422fc8362SDavid Xu.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED"
235c9304272SJohn Baldwin.It Sy Signal Ta Sy Member Ta Sy Value
236b6514098SUlrich Spörlein.It Dv SIGCHLD Ta Va si_pid Ta
23722fc8362SDavid Xuchild process ID
23822fc8362SDavid Xu.It Ta Va si_status Ta
23985213a80SRuslan Ermilovexit value or signal; if
24022fc8362SDavid Xu.Va si_code
24122fc8362SDavid Xuis equal to
24222fc8362SDavid Xu.Dv CLD_EXITED ,
24322fc8362SDavid Xuthen it is equal to the exit value of the child process, otherwise,
24422fc8362SDavid Xuit is equal to a signal that caused the child process to change state.
24522fc8362SDavid Xu.It Ta Va si_uid Ta "real user ID of the process that sent the signal"
24622fc8362SDavid Xu.It Dv SIGPOLL Ta Va si_band Ta "band event for"
24722fc8362SDavid Xu.Dv POLL_IN , POLL_OUT ,
24822fc8362SDavid Xuor
24922fc8362SDavid Xu.Dv POLL_MSG
25022fc8362SDavid Xu.El
25122fc8362SDavid Xu.Pp
25222fc8362SDavid XuFinally, the following code-specific information is available:
253c9304272SJohn Baldwin.Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun"
254c9304272SJohn Baldwin.It Sy Code Ta Sy Member Ta Sy Value
255a4c22c27SJilles Tjoelker.It Dv SI_USER Ta Va si_pid Ta
256a4c22c27SJilles Tjoelkerthe process ID that sent the signal
257a4c22c27SJilles Tjoelker.It Ta Va si_uid Ta
258a4c22c27SJilles Tjoelkerreal user ID of the process that sent the signal
25922fc8362SDavid Xu.It Dv SI_QUEUE Ta Va si_value Ta
26022fc8362SDavid Xuthe value passed to
26122fc8362SDavid Xu.Xr sigqueue 2
26222fc8362SDavid Xusystem call
26322fc8362SDavid Xu.It Ta Va si_pid Ta
26422fc8362SDavid Xuthe process ID that sent the signal
26522fc8362SDavid Xu.It Ta Va si_uid Ta
26622fc8362SDavid Xureal user ID of the process that sent the signal
26722fc8362SDavid Xu.It Dv SI_TIMER Ta Va si_value Ta
26822fc8362SDavid Xuthe value passed to
26922fc8362SDavid Xu.Xr timer_create 2
27022fc8362SDavid Xusystem call
27122fc8362SDavid Xu.It Ta Va si_timerid Ta
27222fc8362SDavid Xuthe timer ID returned by
27322fc8362SDavid Xu.Xr timer_create 2
27422fc8362SDavid Xusystem call
27522fc8362SDavid Xu.It Ta Va si_overrun Ta
27622fc8362SDavid Xutimer overrun count corresponding to the signal
27722fc8362SDavid Xu.It Ta Va si_errno Ta
27822fc8362SDavid XuIf timer overrun will be
27922fc8362SDavid Xu.Brq Dv DELAYTIMER_MAX ,
28022fc8362SDavid Xuan error code defined in
28122fc8362SDavid Xu.In errno.h
28222fc8362SDavid Xuis set
28322fc8362SDavid Xu.It Dv SI_ASYNCIO Ta Va si_value Ta
28422fc8362SDavid Xuthe value passed to aio system calls
28522fc8362SDavid Xu.It Dv SI_MESGQ Ta Va si_value Ta
28622fc8362SDavid Xuthe value passed to
28722fc8362SDavid Xu.Xr mq_notify 2
28822fc8362SDavid Xusystem call
28922fc8362SDavid Xu.It Ta Va si_mqd Ta
29022fc8362SDavid Xuthe ID of the message queue which generated the signal
2915437c0d6SJilles Tjoelker.It Dv SI_LWP Ta Va si_pid Ta
2925437c0d6SJilles Tjoelkerthe process ID that sent the signal
2935437c0d6SJilles Tjoelker.It Ta Va si_uid Ta
2945437c0d6SJilles Tjoelkerreal user ID of the process that sent the signal
29522fc8362SDavid Xu.El
29622fc8362SDavid Xu.Sh NOTES
29785213a80SRuslan ErmilovCurrently, the kernel never generates the
298dbcf945aSDavid Xu.Dv SIGPOLL
299dbcf945aSDavid Xusignal.
30022fc8362SDavid Xu.Dv SIGCHLD
301dbcf945aSDavid Xusignal is queued when a process changed its status or exited.
30222fc8362SDavid Xu.Tn POSIX
30385213a80SRuslan ErmilovRealtime Extensions like aio, timer, and message queue also queue
30422fc8362SDavid Xusignals.
305a4c22c27SJilles TjoelkerSignals with code
3065437c0d6SJilles Tjoelker.Dv SI_USER ,
307a4c22c27SJilles Tjoelker.Dv SI_KERNEL
3085437c0d6SJilles Tjoelkeror
3095437c0d6SJilles Tjoelker.Dv SI_LWP
310a4c22c27SJilles Tjoelkerare only queued if there are sufficient resources;
311a4c22c27SJilles Tjoelkerotherwise,
312a4c22c27SJilles Tjoelker.Dv SI_NOINFO
313a4c22c27SJilles Tjoelkerresults.
31422fc8362SDavid XuFor some hardware architectures, the exact value of
31522fc8362SDavid Xu.Va si_addr
31622fc8362SDavid Xumight not be available.
31722fc8362SDavid Xu.Sh SEE ALSO
31822fc8362SDavid Xu.Xr aio_read 2 ,
31922fc8362SDavid Xu.Xr kill 2 ,
32022fc8362SDavid Xu.Xr mq_notify 2 ,
32122fc8362SDavid Xu.Xr sigaction 2 ,
32222fc8362SDavid Xu.Xr sigqueue 2 ,
32322fc8362SDavid Xu.Xr sigwaitinfo 2 ,
32422fc8362SDavid Xu.Xr timer_create 2 ,
32522fc8362SDavid Xu.Xr timer_settime 2 ,
326a4c22c27SJilles Tjoelker.Xr waitpid 2 ,
327a4c22c27SJilles Tjoelker.Xr pthread_kill 3
32822fc8362SDavid Xu.Sh STANDARDS
32922fc8362SDavid XuThe
33022fc8362SDavid Xu.Vt siginfo_t
33122fc8362SDavid Xutype conforms to
33222fc8362SDavid Xu.St -p1003.1-2004 .
33322fc8362SDavid Xu.Sh HISTORY
33422fc8362SDavid XuFull support for
33522fc8362SDavid Xu.Tn POSIX
33622fc8362SDavid Xusignal information first appeared in
33722fc8362SDavid Xu.Fx 7.0 .
338a4c22c27SJilles TjoelkerThe codes
339a4c22c27SJilles Tjoelker.Dv SI_USER
340a4c22c27SJilles Tjoelkerand
341a4c22c27SJilles Tjoelker.Dv SI_KERNEL
342a4c22c27SJilles Tjoelkercan be generated as of
343a4c22c27SJilles Tjoelker.Fx 8.1 .
3445437c0d6SJilles TjoelkerThe code
3455437c0d6SJilles Tjoelker.Dv SI_LWP
3465437c0d6SJilles Tjoelkercan be generated as of
3475437c0d6SJilles Tjoelker.Fx 9.0 .
34822fc8362SDavid Xu.Sh AUTHORS
34922fc8362SDavid XuThis manual page was written by
350a63d6c94SBaptiste Daroussin.An David Xu Aq Mt davidxu@FreeBSD.org .
351