The siginfo_t argument to a SA_SIGINFO handler

When the SA_SIGINFO flag is specified in act.sa_flags, the signal handler address is passed via the act.sa_sigaction field. This handler takes three arguments, as follows:

void
handler(int sig, siginfo_t *info, void *ucontext)
{


    ...
}

These three arguments are as follows

sig

The number of the signal that caused invocation of the handler.

info

A pointer to a siginfo_t, which is a structure containing further information about the signal, as described below.

ucontext

This is a pointer to a ucontext_t structure, cast to void *. The structure pointed to by this field contains signal context information that was saved on the user-space stack by the kernel; for details, see sigreturn(2). Further information about the ucontext_t structure can be found in getcontext(3) and signal(7). Commonly, the handler function doesn't make any use of the third argument.

The siginfo_t data type is a structure with the following fields:

siginfo_t {


    int      si_signo;     /* Signal number */


    int      si_errno;     /* An errno value */


    int      si_code;      /* Signal code */


    int      si_trapno;    /* Trap number that caused


                              hardware-generated signal


                              (unused on most architectures) */


    pid_t    si_pid;       /* Sending process ID */


    uid_t    si_uid;       /* Real user ID of sending process */


    int      si_status;    /* Exit value or signal */


    clock_t  si_utime;     /* User time consumed */


    clock_t  si_stime;     /* System time consumed */


    union sigval si_value; /* Signal value */


    int      si_int;       /* POSIX.1b signal */


    void    *si_ptr;       /* POSIX.1b signal */


    int      si_overrun;   /* Timer overrun count;


                              POSIX.1b timers */


    int      si_timerid;   /* Timer ID; POSIX.1b timers */


    void    *si_addr;      /* Memory location which caused fault */


    long     si_band;      /* Band event (was int in


                              glibc 2.3.2 and earlier) */


    int      si_fd;        /* File descriptor */


    short    si_addr_lsb;  /* Least significant bit of address


                              (since Linux 2.6.32) */


    void    *si_lower;     /* Lower bound when address violation


                              occurred (since Linux 3.19) */


    void    *si_upper;     /* Upper bound when address violation


                              occurred (since Linux 3.19) */


    int      si_pkey;      /* Protection key on PTE that caused


                              fault (since Linux 4.6) */


    void    *si_call_addr; /* Address of system call instruction


                              (since Linux 3.5) */


    int      si_syscall;   /* Number of attempted system call


                              (since Linux 3.5) */


    unsigned int si_arch;  /* Architecture of attempted system call


                              (since Linux 3.5) */
}

si_signo, si_errno i si_code są zdefiniowane dla wszystkich sygnałów. (Generalnie si_errno nie jest używane pod Linuksem). Pozostałe pola struktury mogą być unią; powinno się odczytywać tylko pola istotne dla danego sygnału.

• Sygnały wysłane przez kill(2) i sigqueue(3) mają wypełnione pola si_pid oraz si_uid. Dodatkowo sygnały wysłane przez sigqueue(3) mają w polach si_int i si_ptr ustawione wartości podane przez nadawcę sygnału; szczegóły opisano w sigqueue(3).
• Sygnały wysłane przez timery POSIX.1b (od Linuksa 2.6) mają uzupełnione pola si_overrun i si_timerid. Pole si_timerid zawiera wewnętrzny identyfikator używany przez jądro do identyfikacji timera; nie jest to ten sam identyfikator, który zwraca timer_create(2). Pole si_overrun zawiera informację o tym, ile razy timer się przepełnił — jest to ta sama informacja, którą zwraca timer_getoverrun(2). Pola te są niestandardowymi rozszerzeniami Linuksa.
• Sygnały wysłane w celu notyfikacji kolejki komunikatów (patrz opis SIGEV_SIGNAL in mq_notify(3)) mają pola si_int/si_ptr wypełnione wartościami sigev_value przekazanymi do mq_notify(3); ponadto si_pid zawiera identyfikator procesu wysyłającego sygnał, a si_uid rzeczywisty identyfikator użytkownika - nadawcy sygnału.
• SIGCHLD ustawia pola si_pid, si_uid, si_status, si_utime i si_stime, dostarczając informacji o procesie potomnym. Pole si_pid jest identyfikatorem potomka, si_uid jest identyfikatorem rzeczywistego użytkownika procesu potomnego. Pole si_status zawiera kod zakończenia potomka (jeśli si_code jest równe CLD_EXITED) lub numer sygnału, który spowodował zmianę stanu. Pola si_utime i si_stime zawierają czasy spędzone przez potomka w przestrzeniach użytkownika i systemowej; w przeciwieństwie do getrusage(2) i times(2), pola te nie zawierają czasów oczekiwania na potomków. W jądrach wcześniejszych niż 2.6, a także w 2.6.27 i nowszych, pola zawierają czas CPU w jednostkach sysconf(_SC_CLK_TCK). W jądrach 2.6 wcześniejszych niż 2.6.27 z powodu błędu używane były (konfigurowalne) jednostki jiffy (patrz time(7)).
• SIGILL, SIGFPE, SIGSEGV, SIGBUS oraz SIGTRAP wypełniają pole si_addr, ustawiając w nim adres błędu. Na niektórych architekturach sygnały wypełniają także pole si_trapno.

Niektóre błędy pochodne SIGBUS, w szczególności BUS_MCEERR_AO i BUS_MCEERR_AR ustawiają także si_addr_lsb. Pole to oznacza najmniej znaczący bit adresu, zatem i rozmiary uszkodzeń. Na przykład jeśli cała strona została uszkodzona, si_addr_lsb zawierać będzie log2(sysconf(_SC_PAGESIZE)). Gdy jako odpowiedź na zdarzenie ptrace(2) (PTRACE_EVENT_foo) zostanie dostarczony SIGTRAP, pole si_addr nie jest wypełnione, natomiast pola si_pid i si_uid są wypełnione identyfikatorami odpowiednio procesu i użytkownika odpowiedzialnego za dostarczenie pułapki. W przypadku seccomp(2) jako dostarczenie zdarzenia pokazany zostanie zrzut. BUS_MCERR_* i si_addr_lsb są rozszerzeniami specyficznymi dla Linuksa.

SEGV_BNDERR będący podbłędem SIGSEGV wypełnia pola si_lower i si_upper.

SEGV_PKUERR będący podbłędem SIGSEGV wypełnia pole si_pkey.

• SIGIO/SIGPOLL (te dwie nazwy są synonimami pod Linuksem) wypełnia pola si_band i si_fd. Zdarzenie si_band jest maską bitową zawierającą te same wartości, które poll(2) umieszcza w polu revents. Pole si_fd oznacza deskryptor pliku, na którym wystąpiło dane zdarzenie wejścia/wyjścia; więcej szczegółów w opisie F_SETSIG w podręczniku fcntl(2).
• SIGSYS, generowany (od Linuksa 3.5) gdy filtr seccomp zwróci SECCOMP_RET_TRAP, wypełnia pola si_call_addr, si_syscall, si_arch, si_errno i inne, zgodnie z opisem z seccomp(2).

The si_code field

The si_code field inside the siginfo_t argument that is passed to a SA_SIGINFO signal handler is a value (not a bit mask) indicating why this signal was sent. For a ptrace(2) event, si_code will contain SIGTRAP and have the ptrace event in the high byte:

(SIGTRAP | PTRACE_EVENT_foo << 8).

For a non-ptrace(2) event, the values that can appear in si_code are described in the remainder of this section. Since glibc 2.20, the definitions of most of these symbols are obtained from <signal.h> by defining feature test macros (before including any header file) as follows:

• _XOPEN_SOURCE with the value 500 or greater;
• _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED; or
• _POSIX_C_SOURCE with the value 200809L or greater.

For the TRAP_* constants, the symbol definitions are provided only in the first two cases. Before glibc 2.20, no feature test macros were required to obtain these symbols.

For a regular signal, the following list shows the values which can be placed in si_code for any signal, along with the reason that the signal was generated.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGILL:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGFPE:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGSEGV:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGBUS:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGTRAP:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGCHLD:

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGIO/SIGPOLL:

Następująca wartość może zostać umieszczona w si_code sygnału SIGSYS:

Różnice biblioteki C/jądra

Funkcja opakowująca glibc dla sigaction() daje błąd (EINVAL) przy próbie zmiany dyspozycji dwóch sygnałów czasu rzeczywistego używanych wewnętrznie przez implementację wątkową NPTL. Więcej szczegółów w podręczniku nptl(7).

On architectures where the signal trampoline resides in the C library, the glibc wrapper function for sigaction() places the address of the trampoline code in the act.sa_restorer field and sets the SA_RESTORER flag in the act.sa_flags field. See sigreturn(2).

Oryginalne linuksowe wywołanie systemowe nazywało się sigaction(). Jednak po pojawieniu się sygnałów czasu rzeczywistego w Linuksie 2.2, 32-bitowy typ sigset_t o stałym rozmiarze obsługiwany przez to wywołanie przestał dobrze służyć swemu zadaniu. Z tego powodu, w celu obsługi powiększonego typu sigset_t dodano nowe wywołanie systemowe rt_sigaction(). Nowe wywołanie przyjmuje czwarty argument size_t sigsetsize, który określa rozmiar w bajtach zestawu sygnałów w act.sa_mask i oldact.sa_mask. Argument ten obecnie musi mieć wartość sizeof(sigset_t) (albo nastąpi błąd EINVAL). Opakowanie glibc sigaction() ukrywa te detale przed nami, po cichu wywołując rt_sigaction() jeśli udostępnia je jądro.

Nieudokumentowane

Before the introduction of SA_SIGINFO, it was also possible to get some additional information about the signal. This was done by providing an sa_handler signal handler with a second argument of type struct sigcontext, which is the same structure as the one that is passed in the uc_mcontext field of the ucontext structure that is passed (via a pointer) in the third argument of the sa_sigaction handler. See the relevant Linux kernel sources for details. This use is obsolete now.