siginfo

SIGINFO(3)               BSD Library Functions Manual               SIGINFO(3)

NAME
     siginfo — signal generation information

SYNOPSIS
     #include <signal.h>

DESCRIPTION
     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:

     Type            Member        Description
     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      address of faulting instruction
     int             si_status     exit value or signal
     long            si_band       band event for SIGPOLL
     int             si_trapno     machine trap code
     int             si_timerid    POSIX timer ID
     int             si_overrun    POSIX timer overrun count
     int             si_mqd        POSIX message queue ID

     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:

     Signal     Code             Reason
     SIGILL     ILL_ILLOPC       illegal opcode
                ILL_ILLOPN       illegal operand
                ILL_ILLADR       illegal addressing mode
                ILL_ILLTRP       illegal trap
                ILL_PRVOPC       illegal privileged opcode
                ILL_PRVREG       illegal privileged register
                ILL_COPROC       coprocessor error
                ILL_BADSTK       internal stack error
     SIGFPE     FPE_INTDIV       integer divide by zero
                FPE_INTOVF       integer overflow
                FPE_FLTDIV       floating-point divide by zero
                FPE_FLTOVF       floating-point overflow
                FPE_FLTUND       floating-point underflow
                FPE_FLTRES       floating-point inexact result
                FPE_FLTINV       invalid floating-point operation
                FPE_FLTSUB       subscript out of range
     SIGSEGV    SEGV_MAPERR      address not mapped to object
                SEGV_ACCERR      invalid permissions for mapped object
     SIGBUS     BUS_ADRALN       invalid address alignment
                BUS_ADRERR       nonexistent physical address
                BUS_OBJERR       object-specific hardware error
     SIGTRAP    TRAP_BRKPT       process breakpoint
                TRAP_TRACE       process trace trap
                TRAP_DTRACE      DTrace induced trap
                TRAP_CAP         capabilities protective trap
     SIGCHLD    CLD_EXITED       child has exited
                CLD_KILLED       child has terminated abnormally and did not
                                 create a core file
                CLD_DUMPED       child has terminated abnormally and created a
                                 core file
                CLD_TRAPPED      traced child has trapped
                CLD_STOPPED      child has stopped
                CLD_CONTINUED    stopped child has continued
     SIGPOLL    POLL_IN          data input available
                POLL_OUT         output buffers available
                POLL_MSG         input message available
                POLL_ERR         I/O error
                POLL_PRI         high priority input available
                POLL_HUP         device disconnected
     Any        SI_NOINFO        Only the si_signo member is meaningful; the
                                 value of all other members is unspecified.
                SI_USER          signal sent by kill(2)
                SI_QUEUE         signal sent by sigqueue(2)
                SI_TIMER         signal generated by expiration of a timer set
                                 by timer_settime(2)
                SI_ASYNCIO       signal generated by completion of an
                                 asynchronous I/O request
                SI_MESGQ         signal generated by arrival of a message on
                                 an empty message queue
                SI_KERNEL        signal generated by miscellaneous parts of
                                 the kernel
                SI_LWP           signal sent by pthread_kill(3)

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

     Signal     Member           Value
     SIGILL     si_addr          address of faulting instruction
                si_trapno        machine dependent of trap code
     SIGFPE     si_addr          address of faulting instruction
                si_trapno        machine dependent of trap code
     SIGSEGV    si_addr          address of faulting memory reference
                si_trapno        machine dependent of trap code
     SIGBUS     si_addr          address of faulting instruction
                si_trapno        machine dependent of trap code
     SIGCHLD    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
     SIGPOLL    si_band          band event for POLL_IN, POLL_OUT, or POLL_MSG

     Finally, the following code-specific information is available:

     Code          Member        Value
     SI_USER       si_pid        the process ID that sent the signal
                   si_uid        real user ID of the process that sent the
                                 signal
     SI_QUEUE      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_TIMER      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_ASYNCIO    si_value      the value passed to aio system calls
     SI_MESGQ      si_value      the value passed to mq_notify(2) system call
                   si_mqd        the ID of the message queue which generated
                                 the signal
     SI_LWP        si_pid        the process ID that sent the signal
                   si_uid        real user ID of the process that sent the
                                 signal

NOTES
     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.

SEE ALSO
     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)

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

HISTORY
     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.

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

BSD                             April 24, 2018                             BSD