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;    /* Numer sygnału */
    int      si_errno;    /* Wartość zmiennej errno */
    int      si_code;     /* Kod sygnału */
    int      si_trapno;   /* Numer pułapki, które spowodowała
                             sprzętowe wygenerowanie sygnału
                             (nieużywane na większości architektur) */
    pid_t    si_pid;      /* ID procesu wysyłającego */
    uid_t    si_uid;      /* Rzeczywiste ID użytk. procesu wysyłającego */
    int      si_status;   /* Kod lub sygnał zakończenia */
    clock_t  si_utime;    /* Czas zużyty w przestrzeni użytkownika */
    clock_t  si_stime;    /* Czas zużyty przez system operacyjny */
    union sigval si_value;  /* Wartość sygnału */
    int      si_int;      /* Sygnał POSIX.1b */
    void    *si_ptr;      /* Sygnał POSIX.1b */
    int      si_overrun;  /* Licznik przekr. timerów; timery POSIX.1b */
    int      si_timerid;  /* ID timera; timery POSIX.1b */
    void    *si_addr;     /* Adres pamięci powodujący błąd */
    long     si_band;     /* Grupa zdarzenia (był int w
                             glibc 2.3.2 i wcześniejszych) */
    int      si_fd;       /* Deskryptor pliku */
    short    si_addr_lsb; /* Mniej istotny bit adresu
                             (od Linuksa 2.6.32) */
    void    *si_lower;    /* Kres dolny przy wystąpieniu naruszenia
                             adresu (od Linuksa 3.19) */
    void    *si_upper;    /* Kres górny przy wystąpieniu naruszenia
                             adresu (od Linuksa 3.19) */
    int      si_pkey;     /* Klucz zabezpieczający na PTE będący powodem
                             błędu (od Linuksa 4.6) */
    void    *si_call_addr;/* Adres instrukcji wywołania systemowego
                             (od Linuksa 3.5) */
    int      si_syscall;  /* Liczba próbowanych wywołań systemowych
                             (od Linuksa 3.5) */
    unsigned int si_arch; /* Architektura próbowanego wywoł. systemowego
                             (od Linuksa 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 fills in si_pid, si_uid, si_status, si_utime, and si_stime, providing information about the child. The si_pid field is the process ID of the child; si_uid is the child's real user ID. The si_status field contains the exit status of the child (if si_code is CLD_EXITED), or the signal number that caused the process to change state. The si_utime and si_stime contain the user and system CPU time used by the child process; these fields do not include the times used by waited-for children (unlike getrusage(2) and times(2)). Up to Linux 2.6, and since Linux 2.6.27, these fields report CPU time in units of sysconf(_SC_CLK_TCK). In Linux 2.6 kernels before Linux 2.6.27, a bug meant that these fields reported time in units of the (configurable) system jiffy (see 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.

W przypadku zwykłego sygnału, poniżej zestawiono wartości, które mogą występować w si_code dowolnego sygnału razem z powodami, dla których sygnał był wygenerowany.

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:

Dynamically probing for flag bit support

The sigaction() call on Linux accepts unknown bits set in act->sa_flags without error. The behavior of the kernel starting with Linux 5.11 is that a second sigaction() will clear unknown bits from oldact->sa_flags. However, historically, a second sigaction() call would typically leave those bits set in oldact->sa_flags.

This means that support for new flags cannot be detected simply by testing for a flag in sa_flags, and a program must test that SA_UNSUPPORTED has been cleared before relying on the contents of sa_flags.

Since the behavior of the signal handler cannot be guaranteed unless the check passes, it is wise to either block the affected signal while registering the handler and performing the check in this case, or where this is not possible, for example if the signal is synchronous, to issue the second sigaction() in the signal handler itself.

In kernels that do not support a specific flag, the kernel's behavior is as if the flag was not set, even if the flag was set in act->sa_flags.

The flags SA_NOCLDSTOP, SA_NOCLDWAIT, SA_SIGINFO, SA_ONSTACK, SA_RESTART, SA_NODEFER, SA_RESETHAND, and, if defined by the architecture, SA_RESTORER may not be reliably probed for using this mechanism, because they were introduced before Linux 5.11. However, in general, programs may assume that these flags are supported, since they have all been supported since Linux 2.6, which was released in the year 2003.

See EXAMPLES below for a demonstration of the use of SA_UNSUPPORTED.

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.

Probing for flag support

The following example program exits with status EXIT_SUCCESS if SA_EXPOSE_TAGBITS is determined to be supported, and EXIT_FAILURE otherwise.

#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
void
handler(int signo, siginfo_t *info, void *context)
{
    struct sigaction oldact;
    if (sigaction(SIGSEGV, NULL, &oldact) == -1
        || (oldact.sa_flags & SA_UNSUPPORTED)
        || !(oldact.sa_flags & SA_EXPOSE_TAGBITS))
    {
        _exit(EXIT_FAILURE);
    }
    _exit(EXIT_SUCCESS);
}
int
main(void)
{
    struct sigaction act = { 0 };
    act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS;
    act.sa_sigaction = &handler;
    if (sigaction(SIGSEGV, &act, NULL) == -1) {
        perror("sigaction");
        exit(EXIT_FAILURE);
    }
    raise(SIGSEGV);
}