Manual Page Search Parameters
SIGINFO(3) Library Functions Manual SIGINFO(3)

siginfo — signal generation information

#include <signal.h>

A process may request signal information when it is catching a signal. The information specifies why the system generated that signal. To request signal information in a signal handler, the user can set SA_SIGINFO in sa_flags before sigaction(2) is called, otherwise the user can use sigwaitinfo(2) and sigtimedwait(2) to get signal information. In either case, the system returns the information in a structure of type siginfo_t, which includes the following information:

int si_signo signal number
int si_errno error number
int si_code signal code
union sigval si_value signal value
pid_t si_pid sending process ID
uid_t si_uid sending process's real user ID
void *si_addr virtual address
int si_status exit value or signal
long si_band band event for SIGPOLL
int si_trapno machine trap code
int si_capreg capability register number
int si_timerid POSIX timer ID
int si_overrun POSIX timer overrun count
int si_mqd POSIX message queue ID
int si_syscall system-call number for system calls blocked by Capsicum

The si_signo member contains the signal number.

The si_errno member contains an error number defined in the file <errno.h>.

The si_code member contains a code which describes the cause of the signal. The macros specified in the Code column of the following table are defined for use as values of si_code that are signal-specific or non-signal-specific reasons why the signal was generated:

illegal opcode
illegal operand
illegal addressing mode
illegal trap
illegal privileged opcode
illegal privileged register
coprocessor error
internal stack error
integer divide by zero
integer overflow
floating-point divide by zero
floating-point overflow
floating-point underflow
floating-point inexact result
invalid floating-point operation
subscript out of range
address not mapped to object
invalid permissions for mapped object
invalid address alignment
nonexistent physical address
object-specific hardware error
cannot alloc a page to map at fault
capability bounds fault
capability tag fault
capability sealed fault
type mismatch fault
capability permission fault
imprecise bounds fault
store-local fault
CInvoke fault
capability system register fault
unaligned base address
process breakpoint
process trace trap
DTrace induced trap
capabilities protective trap
child has exited
child has terminated abnormally and did not create a core file
child has terminated abnormally and created a core file
traced child has trapped
child has stopped
stopped child has continued
data input available
output buffers available
input message available
I/O error
high priority input available
device disconnected
Any Only the si_signo member is meaningful; the value of all other members is unspecified.
signal sent by kill(2)
signal sent by sigqueue(2)
signal generated by expiration of a timer set by timer_settime(2)
signal generated by completion of an asynchronous I/O request
signal generated by arrival of a message on an empty message queue
signal generated by miscellaneous parts of the kernel
signal sent by pthread_kill(3)

For synchronous signals, si_addr is generally set to the address of the faulting instruction. However, synchronous signals raised by a faulting memory access such as SIGSEGV and SIGBUS may report the address of the faulting memory access (if available) in si_addr instead. Additionally SIGTRAP raised by a hardware watchpoint exception may report the data address that triggered the watchpoint in si_addr.

Sychronous signals set si_trapno to a machine-dependent trap number.

In addition, the following signal-specific information is available:

si_addr address of faulting instruction
si_trapno machine dependent of trap code
si_capreg capability register number
si_pid child process ID
si_status exit value or signal; if si_code is equal to CLD_EXITED, then it is equal to the exit value of the child process, otherwise, it is equal to a signal that caused the child process to change state.
si_uid real user ID of the process that sent the signal
si_band band event for POLL_IN, POLL_OUT, or POLL_MSG

Finally, the following code-specific information is available:

si_pid the process ID that sent the signal
si_uid real user ID of the process that sent the signal
si_value the value passed to sigqueue(2) system call
si_pid the process ID that sent the signal
si_uid real user ID of the process that sent the signal
si_value the value passed to timer_create(2) system call
si_timerid the timer ID returned by timer_create(2) system call
si_overrun timer overrun count corresponding to the signal
si_errno If timer overrun will be {DELAYTIMER_MAX}, an error code defined in <errno.h> is set
si_value the value passed to aio system calls
si_value the value passed to mq_notify(2) system call
si_mqd the ID of the message queue which generated the signal
si_pid the process ID that sent the signal
si_uid real user ID of the process that sent the signal

Currently, the kernel never generates the SIGPOLL signal. SIGCHLD signal is queued when a process changed its status or exited. POSIX Realtime Extensions like aio, timer, and message queue also queue signals. Signals with code SI_USER, SI_KERNEL or SI_LWP are only queued if there are sufficient resources; otherwise, SI_NOINFO results. For some hardware architectures, the exact value of si_addr might not be available.

aio_read(2), kill(2), mq_notify(2), sigaction(2), sigqueue(2), sigwaitinfo(2), timer_create(2), timer_settime(2), waitpid(2), pthread_kill(3)

The siginfo_t type conforms to IEEE Std 1003.1-2004 (“POSIX.1”).

Full support for POSIX signal information first appeared in FreeBSD 7.0. The codes SI_USER and SI_KERNEL can be generated as of FreeBSD 8.1. The code SI_LWP can be generated as of FreeBSD 9.0.

This manual page was written by David Xu <davidxu@FreeBSD.org>.

February 17, 2021 dev