Argument siginfo_t do procedury obsługi SA_SIGINFO

Gdy w act.sa_flags poda się znacznik SA_SIGINFO, to adres procedury obsługi sygnału jest przekazywany za pomocą pola act.sa_sigaction. Ta procedura obsługi przyjmuje trzy argumenty jak poniżej:

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

Te trzy argumenty to:

sig

Numer sygnału powodującego przywołanie procedury obsługi.

info

Wskaźnik do siginfo_t, który jest strukturą zawierającą dalsze informacje o sygnale, jak to opisano poniżej.

ucontext

Jest to wskaźnik do struktury ucontext_t rzutowany na void *. Struktura, na którą wskazuje to pole zawiera informacje o kontekście sygnału, które zostały zachowanie w stosie w przestrzeni użytkownika przez jądro; więcej szczegółów w podręczniku sigreturn(2). Dalsze informacje o strukturze ucontext_t można odszukać w podręcznikach getcontext(3) i signal(7). Funkcja obsługi nie czyni zwykle żadnego użytku z trzeciego argumentu.

Typ danych siginfo_t jest strukturą zawierającą następujące pola:

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 użyty w przestrzeni użytkownika */
    clock_t  si_stime;    /* Czas uż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. czasom.; czasom POSIX.1b */
    int      si_timerid;  /* ID czasomierza; czasom. 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; /* Najmniej znaczący 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 czasomierze 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 czasomierza; nie jest to ten sam identyfikator, który zwraca timer_create(2). Pole si_overrun zawiera informację o tym, ile razy czasomierz 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 rzeczywistym identyfikatorem 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. Do Linuksa 2.6 oraz od Linuksa 2.6.27, pola zawierają czas CPU w jednostkach sysconf(_SC_CLK_TCK). W Linuksie 2.6 przed Linuksem 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).

Pole si_code

Pole si_code, wewnątrz argumentu siginfo_t, które jest przekazywane do procedury obsługi sygnału SA_SIGINFO, jest wartością (a nie maską bitową) określającą powód wysłania sygnału. Dla zdarzenia ptrace(2), pole si_code będzie zawierać SIGTRAP i mieć zdarzenie ptrace w najwyższym bajcie:

(SIGTRAP | PTRACE_EVENT_foo << 8).

Dla zdarzeń innych niż ptrace(2), wartości jakie mogą wystąpić w si_code są opisane w pozostałej części niniejszego rozdziału. Od glibc 2.20, definicje większości z tych symboli są pozyskiwane z <signal.h> za pomocą definicji makr testowania cech (przed włączeniem jakiegokolwiek pliku nagłówkowego), jak poniżej:

•

_XOPEN_SOURCE z wartością 500 lub większą;

•

_XOPEN_SOURCE i _XOPEN_SOURCE_EXTENDED; albo

•

_POSIX_C_SOURCE z wartością 200809L lub większą.

Dla stałych TRAP_*, definicje symboli są zapewnione jedynie w dwóch pierwszych przypadkach. Przed glibc 2.20, nie było konieczne ustawianie makr, do pozyskania tych symboli.

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:

Dynamiczne sprawdzanie obsługiwanych bitów znaczników

Wywołanie sigaction() w Linuksie akceptuje nieznane bity ustawione w act->sa_flags nie zgłaszając błędu. Zachowanie jądra, od Linuksa 5.11 jest takie, że drugie sigaction() wyczyści nieznane bity z oldact->sa_flags. Jednak historycznie, drugie wywołanie zwykle pozostawiało te bity ustawione w oldact->sa_flags.

Oznacza to, że nie da się wykryć obsługi nowych znaczników jedynie sprawdzając znacznik w sa_flags, lecz konieczne jest sprawdzenie, czy SA_UNSUPPORTED zostało wyczyszczone, przed poleganiem na zawartości sa_flags.

Ponieważ zachowania procedury obsługi sygnału nie można zagwarantować, jeśli nie dokonano sprawdzenia, powinno się albo blokować dany sygnał podczas rejestrowania procedury obsługi i wykonać w takim przypadku sprawdzenie, albo — tam, gdzie nie jest to możliwe, np. gdy sygnał jest asynchroniczny — wywołać sigaction() po raz drugi z samej procedury obsługi sygnału.

W jądrach nieobsługujących danego znacznika, jądro zachowa się tak, jakby znacznik ten nie był ustawiony, nawet jeśli znacznik był ustawiony w act->sa_flags.

Znaczników SA_NOCLDSTOP, SA_NOCLDWAIT, SA_SIGINFO, SA_ONSTACK, SA_RESTART, SA_NODEFER, SA_RESETHAND i, jeśli jest zdefiniowany na danej architekturze, SA_RESTORER nie da się wiarygodnie sprawdzić za pomocą opisywanego mechanizmu, ponieważ zostały one wprowadzone przez Linuksem 5.11. Zwykle jednak, programy mogą przyjąć, że znaczniki te są obsługiwane, ponieważ wszystkie były obsługiwane już od Linuksa 2.6, wydanego w roku 2003.

W rozdziale PRZYKŁADY poniżej, zademonstrowano korzystanie z 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).

Na architekturach, na których trampolina sygnału jest zawarta w bibliotece C, funkcja opakowujące sigaction() z glibc, umieszcza adres kodu trampoliny w polu act.sa_restorer i ustawia znacznik SA_RESTORER w polu act.sa_flags. Zob. 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

Przed wprowadzeniem SA_SIGINFO również było możliwe otrzymanie pewnych dodatkowych informacji o sygnale. Działo się to poprzez użycie procedury obsługi sygnału sa_handler z drugim argumentem, będącym typu struct sigcontext, który jest taką samą strukturą jak ta przekazywana w polu uc_mcontext struktury ucontext, przekazywanym (wskaźnikiem) w trzecim argumencie procedury obsługi sa_sigaction. Szczegóły można znaleźć w odpowiednich źródłach jądra Linux. To użycie jest obecnie przestarzałe.

Sprawdzanie obsługiwanych znaczników

Poniższy przykładowy program wychodzi ze statusem EXIT_SUCCESS gdy sprawdzi, że SA_EXPOSE_TAGBITS jest obsługiwany albo EXIT_FAILURE w przeciwnym przypadku.

#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);
}