Le paramètre siginfo_t vers un gestionnaire SA_SIGINFO

Quand le drapeau SA_SIGINFO est indiqué à act.sa_flags, l'adresse du gestionnaire de signal est passée à l'aide du champ act.sa_sigaction. Ce gestionnaire prend trois paramètres comme suit :

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

Ces trois paramètres sont comme suit

sig

Le numéro de signal qui a provoqué l'appel du gestionnaire.

info

Un pointeur vers un siginfo_t, qui est une structure contenant plus d'informations sur le signal comme décrit ci-dessous.

ucontext

Il s'agit d'un pointeur vers une structure ucontext_t, diffusée sur void\ *. La structure vers laquelle pointe ce champ contient des informations contextuelles sur le signal sauvegardées dans la pile de l'espace utilisateur par le noyau ; pour des détails, consultez sigreturn(2). Vous pouvez trouver plus d'informations sur la structure ucontext_t dans getcontext(3) et signal(7). Généralement, la fonction de gestionnaire n'utilise pas le troisième paramètre.

Le type de données siginfo_t est une structure contenant les champs suivants :

siginfo_t {
    int      si_signo;    /* Numéro de signal           */
    int      si_errno;    /* Numéro d'erreur            */
    int      si_code;     /* Code du signal             */
    int      si_trapno;   /* Numéro de trappe qui a causé
                             le signal généré par le
                             matériel (pas utilisé sur la
                             plupart des architectures) */
    pid_t    si_pid;      /* PID de l'émetteur          */
    uid_t    si_uid;      /* UID réel de l'émetteur     */
    int      si_status;   /* Valeur de sortie ou signal */
    clock_t  si_utime;    /* Temps utilisateur écoulé   */
    clock_t  si_stime;    /* Temps système écoulé       */
    union sigval si_value; /* Valeur du signal */
    int      si_int;      /* Signal POSIX.1b            */
    void    *si_ptr;      /* Signal POSIX.1b            */
    int      si_overrun;  /* Décompte de dépassement des
                             horloges (POSIX.1b)        */
    int      si_timerid;  /* ID d'horloge (POSIX.1b)    */
    void    *si_addr;     /* Emplacement mémoire ayant
                             causé l'erreur             */
    long     si_band;     /* Band event (était int dans
                             glibc 2.3.2 et antérieures */
    int      si_fd;       /* Descripteur de fichier     */
    short    si_addr_lsb; /* Bit le moins significatif de l'adresse
                             (depuis Linux 2.6.32)   */
    void    *si_lower;     /* Limite inférieure lorsqu'une violation
                              d'adresse se produit (depuis Linux 3.19) */
    void    *si_upper;     /* Limite supérieure lorsqu'une violation
                              d'adresse se produit (depuis Linux 3.19) */
    int      si_pkey;      /* Clé de protection PTE à l'origine de
                              l'ereur (depuis Linux 4.6) */
    void    *si_call_addr; /* Adresse de l'instruction d'appel système
                              (depuis Linux 3.5) */
    int      si_syscall;   /* Nombre d'appels système essayés
                              (depuis Linux 3.5) */
    unsigned int si_arch;  /* Architecture des appels système essayés
                              (depuis Linux 3.5) */
}

si_signo, si_errno et si_code sont définis pour tous les signaux (si_errno n'est généralement pas utilisé sous Linux). Le reste de la structure peut être une union, de telle sorte qu'on puisse ne lire que les champs spécifiques à un signal donné :

• Les signaux envoyés avec kill(2) et sigqueue(3) remplissent si_pid et si_uid. De plus, les signaux envoyés avec sigqueue(3) remplissent si_int et si_ptr avec les valeurs indiquées par l'émetteur du signal ; consultez sigqueue(3) pour plus de détails.
• Les signaux envoyés par les horloges POSIX.1b (depuis Linux 2.6) remplissent si_overrun et si_timerid. Le champ si_timerid est un identifiant interne utilisé par le noyau pour identifier l'horloge ; ce n'est pas la même chose que l'identifient d'horloge renvoyé par timer_create(2). Le champ si_overrun est le compteur de dépassement de l'horloge ; il s'agit de la même information renvoyée par un appel à timer_getoverrun(2). Ces champs sont des extensions Linux non standard.
• Les signaux envoyés pour les notifications de files de messages (voyez la description de SIGEV_SIGNAL dans mq_notify(3)) remplissent si_int/si_ptr avec la valeur sigev_value fournie à mq_notify(3) ; si_pid avec l'identifiant du processus de l'émetteur du message ; et si_uid avec l'identifiant d'utilisateur réel de l'émetteur du message.
• SIGCHLD remplit si_pid, si_uid, si_status, si_utime et si_stime, pour fournir des informations au sujet des enfants. Le champ si_pid est l'identifiant de processus de l'enfant ; si_uid est l'identifiant d'utilisateur réel de l'enfant. Le champ si_status contient le code de sortie de l'enfant (si si_code vaut CLD_EXITED), ou le numéro du signal qui a changé l'etat du processus. Les champs si_utime et si_stime comprennent les temps utilisateur et système utilisé par le processus enfant ; ces champs ne comprennent pas le temps utilisé par les enfants lorsqu'ils sont attendus (au contraire de getrusage(2) et times(2)). Jusqu'à Linux 2.6, et depuis Linux 2.6.27, ces champs renvoient le temps CPU en unité de sysconf(_SC_CLK_TCK). Dans les noyaux Linux 2.6, avant Linux 2.6.27, un bogue faisait que ces champs renvoyaient des temps mesurés en jiffy système (configurable) (consultez time(7)).
• SIGILL, SIGFPE, SIGSEGV, SIGBUS et SIGTRAP remplissent si_addr avec l'adresse de l'erreur. Sur certaines architectures, ces signaux remplissent aussi le champ si_trapno.

Certaines sous-erreurs de SIGBUS, en particulier BUS_MCEERR_AO et BUS_MCEERR_AR, remplissent également si_addr_lsb. Ce champ indique le bit le moins significatif de l'adresse signalée et, donc, l'étendue de la corruption. Par exemple, si toute une page est corrompue, si_addr_lsb contient log2(sysconf(_SC_PAGESIZE)). Lorsque SIGTRAP est délivré en réponse à un événement ptrace(2) ((PTRACE_EVENT_foo), si_addr n'est pas peuplé mais si_pid et si_uid le sont avec leur identifiant de processus et d'utilisateur respectifs responsables de cette trappe. Dans le cas de seccomp(2), le traceur sera affiché comme délivrant un événement. BUS_MCEERR_* et si_addr_lsb sont des extensions spécifiques à Linux.

La sous-erreur de SEGV_BNDERR de SIGSEGV peuple si_lower et si_upper.

La sous-erreur SEGV_PKUERR de SIGSEGV peuple si_pkey.

• SIGPOLL/SIGIO (synonymes sous Linux) remplissent si_band et si_fd. L'événement si_band est un masque de bits contenant les mêmes valeurs que celles qui sont remplies dans le champ revents par poll(2). Le champ si_fd donne le descripteur de fichiers sur lequel l'événement d'entrées-sorties s'est produit. Pour plus de détails, voir la description de F_SETSIG dans fcntl(2).
• SIGSYS, généré (depuis Linux 3.5) quand un filtre seccomp renvoie SECCOMP_RET_TRAP, remplit si_call_addr, si_syscall, si_arch, si_errno et d'autres décrits dans seccomp(2).

Le champ si_code

Le champ si_code du paramètre siginfo_t passé à un gestionnaire de signal SA_SIGINFO est une valeur (et non un masque de bit) indiquant la raison de l'envoi de ce signal. Pour un événement ptrace(2), si_code contiendra SIGTRAP et aura l'événement ptrace dans l'octet fort :

(SIGTRAP | PTRACE_EVENT_foo << 8).

Pour un événement non ptrace(2), les valeurs qui peuvent apparaître dans si_code sont décrites dans le reste de cette section. Depuis la glibc 2.20, les définitions de la plupart de ces symboles viennent de <signal.h> en définissant des macros de test de fonctionnalités (avant l'inclusion de tout fichier d'en-tête) comme suit :

• _XOPEN_SOURCE avec la valeur 500 ou supérieure ;
• _XOPEN_SOURCE et _XOPEN_SOURCE_EXTENDED ; ou
• _POSIX_C_SOURCE avec la valeur 200809L ou supérieure.

Pour les constantes TRAP_*, les définitions de symboles ne sont fournies que dans les deux premiers cas. Avant la glibc 2.20, aucune macro de test n'était nécessaire pour obtenir ces symboles.

Pour un signal normal, la liste suivante indique les valeurs que peut prendre si_code pour n'importe quel signal, avec la raison associée.

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGILL :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGFPE :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGSEGV :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGBUS :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGTRAP :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGCHLD :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGIO/SIGPOLL :

Les valeurs suivantes peuvent être prises par si_code pour un signal SIGSYS :

Sondage dynamique de la prise en charge des bits de drapeau

L'appel sigaction() sur Linux accepte des jeux de bits inconnus act->sa_flags sans erreur. Le comportement du noyau, à partir de Linux 5.11, est qu'un deuxième sigaction(2) videra les bits inconnus de oldact->sa_flags. Toutefois, historiquement, un second appel sigaction() laissait généralement ces ensembles de bits dans oldact->sa_flags.

Cela signifie que la prise en charge de nouveaux drapeaux ne peut pas être détectée par un simple test du drapeau sa_flags dans sa_flags et un programme doit tester que SA_UNSUPPORTED a été vidé avant de s'appuyer sur le contenu de sa_flags.

Comme le comportement du gestionnaire ne peut pas être garanti, sauf si la vérification réussit, il vaut mieux soit bloquer le signal concerné tout en enregistrant le gestionnaire puis effectuer la vérification dans ce cas, soit, quand cela n'est pas possible, par exemple si le signal est synchrone, effectuer le deuxième sigaction() dans le gestionnaire de signal lui-même.

Dans les noyaux qui ne prennent pas en charge un drapeau en particulier, le comportement du noyau est le même que si le drapeau n'était pas positionné, même si ce dernier a été positionné avec act->sa_flags.

Les drapeaux SA_NOCLDSTOP, SA_NOCLDWAIT, SA_SIGINFO, SA_ONSTACK, SA_RESTART, SA_NODEFER, SA_RESETHAND et, s'il est défini par l'architecture, SA_RESTORER, peuvent ne pas être sondés de manière fiable si on utilise ce mécanisme, parce qu'ils ont été introduits avant Linux 5.11. Cependant, en général, les programmes peuvent supposer que ces drapeaux sont pris en charge car ils le sont depuis Linux 2.6, publié en 2003.

Consultez les EXEMPLES ci-dessous pour une démonstration de l'utilisation de SA_UNSUPPORTED.

Différences entre bibliothèque C et noyau

La fonction enveloppe de la glibc autour de sigacttion() donne une erreur (EINVAL) lorsqu'on essaie de changer la position des deux signaux en temps réel utilisés en interne par l'implémentation de threading de NPTL. Consultez nptl(7) pour plus de détails.

Sur des architectures où le trampoline du signal se trouve dans la bibliothèque C, la fonction enveloppe de la bibliothèque C autour de sigaction() met l'adresse du code de trampoline dans le champ act.sa_restorer et positionne le drapeau SA_RESTORER du champ act.sa_flags. Consultez sigreturn(2).

L'appel système Linux d'origine s'appelait sigaction(). Toutefois, avec l'arrivée des signaux en temps réel dans Linux 2.2 et de la taille figée, le type sigset_t 32 bits pris en charge par cet appel système ne convenait plus à cet objectif. Par conséquent, un nouvel appel système rt_sigaction() a été ajouté pour prendre en charge le type sigset_t élargi. Le nouvel appel système prend un quatrième paramètre, size_t sigsetsize, qui indique la taille en octets des jeux de signal dans act.sa_mask et oldact.sa_mask. Ce paramètre est actuellement nécessaire pour obtenir la valeur sizeof(sigset_t) (ou le résultat de l'erreur EINVAL). La fonction enveloppe sigaction() de la glibc nous cache ces détails en appelant de manière transparente rt_sigaction() quand le noyau le fournit.

Non documenté

Avant l'introduction de l'attribut SA_SIGINFO il était déjà possible d'obtenir des informations supplémentaires sur un signal. Cela se faisait en fournissant au gestionnaire de signal sa_handler un second paramètre de type struct sigcontext, qui est la même structure que celle fournie dans le champ uc_mcontext de la structure ucontext passée (à l'aide d'un pointeur) comme troisième paramètre du gestionnaire sa_sigaction Consultez les sources du noyau Linux pertinentes pour des détails. Cette utilisation est désormais obsolète.

Sondage de la prise en charge d'un drapeau

Le programme d'exemple suivant quitte avec l'état EXIT_SUCCESS si SA_EXPOSE_TAGBITS a vocation à être pris en charge, ou sinon EXIT_FAILURE.

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