SIGACTION(2)

NOM
sigaction - Examiner et modifier l'action associée à un signal

SYNOPSIS
#include <signal.h>

int sigaction(int signum, const struct sigaction *act,
              struct sigaction *oldact);

Exigences de macros de test de fonctionnalités pour la glibc (consultez feature_test_macros(7)) :

sigaction() : _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION
L'appel système sigaction() sert à modifier l'action effectuée par un processus à la réception d'un signal spécifique. (Consultez signal(7) pour une vue d'ensemble sur les signaux)

signum indique le signal concerné, à l'exception de SIGKILL et SIGSTOP.

Si act n'est pas NULL, la nouvelle action pour le signal signum est définie par act. Si oldact n'est pas NULL, l'ancienne action est sauvegardée dans oldact.

La structure sigaction est définie par quelque chose comme :

struct sigaction {
    void     (*sa_handler)(int);
    void     (*sa_sigaction)(int, siginfo_t *, void *);
    sigset_t   sa_mask;
    int        sa_flags;
    void     (*sa_restorer)(void);
};

Sur certaines architectures, on emploie une union. Il ne faut donc pas utiliser ou remplir simultanément sa_handler et sa_sigaction.

L'élément sa_restorer est obsolète et ne devrait pas être utilisé, POSIX ne mentionne pas de membre sa_restorer.

sa_handler indique l'action affectée au signal signum, et peut être SIG_DFL pour l'action par défaut, SIG_IGN pour ignorer le signal, ou un pointeur sur une fonction de gestion de signaux.

Si SA_SIGINFO est indiqué dans sa_flags, alors sa_sigaction (plutôt que sa_handler) pointe vers le gestionnaire de signal pour signum. Cette fonction prend le numéro du signal comme premier argument, un pointeur vers un siginfo_t comme second argument, et un pointeur vers un ucontext_t (transtypé en void *) comme troisième paramètre. (Généralement, le gestionnaire de signal n'utilise pas le troisième argument. Consultez getcontext(2) pour plus d'informations au sujet de ucontext_t.)

sa_mask spécifie un masque de signaux à bloquer (c'est-à-dire ajoutés au masque de signaux du thread dans lequel le gestionnaire est appelé) pendant l'exécution du gestionnaire. De plus le signal ayant appelé le gestionnaire est bloqué à moins que l'attribut SA_NODEFER soit précisé.

sa_flags spécifie un ensemble d'attributs qui modifient le comportement du signal. Il est formé par un OU binaire « | ») entre les options suivantes :

    SA_NOCLDSTOP
        Si signum vaut SIGCHLD, ne pas recevoir les signaux de notification d'arrêt (quand le fils reçoit un signal SIGSTOP, SIGTSTP, SIGTTIN ou SIGTTOU) ou de relance (quand il reçoit SIGCONT) des processus fils. Consultez wait(2). Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire pour SIGCHLD.

    SA_NOCLDWAIT (depuis Linux 2.6)
        Si signum vaut SIGCHLD, ne pas transformer les fils en zombies lorsqu'ils se terminent. Consultez aussi waitpid(2). Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire pour SIGCHLD, ou lors de la configuration de la disposition de signal de SIG_DFL. Si l'attribut SA_NOCLDWAIT est défini lors de la mise en place d'un gestionnaire pour SIGCHLD, POSIX.1 ne spécifie pas si le signal SIGCHLD est généré lorsqu'un processus fils se termine. Sous Linux, un signal SIGCHLD est généré dans ce cas ; sur d'autres implémentations, il ne l'est pas.

    SA_NODEFER
        Ne pas empêcher un signal d'être reçu depuis l'intérieur de son propre gestionnaire. Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire de signal. SA_NOMASK est un synonyme obsolète et non standard pour cet attribut.

    SA_ONSTACK
        Appeler le gestionnaire avec une pile différente fournie par sigaltstack(2). Si cette pile est indisponible, on utilisera la pile par défaut. Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire de signal.

    SA_RESETHAND
        Rétablir l'action à son comportement par défaut une fois que le gestionnaire a été appelé. Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire de signal. SA_ONESHOT est un synonyme obsolète et non standard pour cet attribut.

    SA_RESTART
        Fournir un comportement compatible avec la sémantique BSD en redémarrant automatiquement les appels système lents interrompus par l'arrivée du signal. Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire de signal. Consultez signal(7) pour une discussion sur le redémarrage d'un appel système.

    SA_SIGINFO (depuis Linux 2.2)
        Le gestionnaire de signal recevra trois arguments, et non plus un seul. Dans ce cas, il faut utiliser le membre sa_sigaction au lieu de sa_handler. Cet attribut n'a de sens que lors de la mise en place d'un gestionnaire de signal.

Le paramètre siginfo_t de la routine sa_sigaction est une structure contenant les éléments 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é       */
    sigval_t si_value;    /* Valeur de 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 le noyau 2.6.32)   */
}
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 lire les champs spécifiques à chaque signaux.

*   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 fils. Le champ si_pid est l'identifiant de processus du fils ; si_uid est l'identifiant d'utilisateur réel du fils. Le champ si_status contient le code de sortie du fils (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 fils ; ces champs ne comprennent pas le temps utilisé par les fils lorsqu'ils sont attendus (au contraire de getrusage(2) et time(2)). Dans les noyaux antérieurs à la version 2.6, et depuis la version 2.6.27, ces champs renvoient le temps CPU en unité de sysconf(_SC_CLK_TCK). Dans les noyaux de la série 2.6, avant le noyau 2.6.27, un bogue faisait que ces champs renvoyaient des temps mesurés en jiffy système (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 catégories d'erreurs de SIGBUS, en particulier BUS_MCEERR_AO et BUS_MCEERR_AR, remplissent aussi le champ si_addr_lsb, qui contient le bit le moins significatif de l'erreur signalée, et permet donc de connaitre l'étendue de la corruption des données. Par exemple, si une page entière est corrompue, si_addr_lsb contient log2(sysconf(_SC_PAGESIZE)). BUS_MCERR_* et si_addr_lsb sont des extensions spécifiques à Linux.

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

si_code est une valeur (pas un masque de bits) qui indique pourquoi ce signal a été envoyé. La liste suivante indique les valeurs que peut prendre si_code pour n'importe quel signal, avec la raison associée.

    SI_USER
        kill(2)

    SI_KERNEL
        Envoyé par le noyau.

    SI_QUEUE
        sigqueue(3)

    SI_TIMER
        Fin d'une temporisation POSIX

    SI_MESGQ
        Changement d'état d'une file de messages (depuis Linux 2.6.6) ; consultez mq_notify(3)

    SI_ASYNCIO
        Fin d'une AIO

    SI_SIGIO
        SIGIO avec file d'attente (seulement dans les noyaux Linux jusqu'aux versions 2.2 ; à partir de Linux 2.4, SIGIO/SIGPOLL remplit si_code de la façon décrite plus bas).

    SI_TKILL
        tkill(2) ou tgkill(2) (depuis Linux 2.4.19)

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

    ILL_ILLOPC
        opcode illégal

    ILL_ILLOPN
        opérande illégale

    ILL_ILLADR
        mode d'adressage illégal

    ILL_ILLTRP
        trappe illégale

    ILL_PRVOPC
        opcode privilégié

    ILL_PRVREG
        registre privilégié

    ILL_COPROC
        erreur de coprocesseur

    ILL_BADSTK
        erreur interne de pile

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

    FPE_INTDIV
        division entière par zéro

    FPE_INTOVF
        débordement entier

    FPE_FLTDIV
        division flottante par zéro

    FPE_FLTOVF
        débordement flottant

    FPE_FLTUND
        débordement inférieur flottant

    FPE_FLTRES
        résultat flottant inexact

    FPE_FLTINV
        opération flottante invalide

    FPE_FLTSUB
        indice hors intervalle

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

    SEGV_MAPERR
        adresse sans objet

    SEGV_ACCERR
        permissions invalides pour l'objet

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

    BUS_ADRALN
        alignement d'adresse invalide

    BUS_ADRERR
        adresse physique inexistante

    BUS_OBJERR
        erreur matérielle spécifique

    BUS_MCEERR_AR (depuis Linux 2.6.32)
        erreur mémoire matérielle consommée lors de vérification de la machine ; action requise.

    BUS_MCEERR_AO (depuis Linux 2.6.32)
        erreur mémoire matérielle détectée dans le processus mais non consommée ; action optionnelle.

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

    TRAP_BRKPT
        point d'arrêt du processus

    TRAP_TRACE
        suivi d'exécution du processus

    TRAP_BRANCH (depuis Linux 2.4)
        suivi des branches prises par le processus

    TRAP_HWBKPT (depuis Linux 2.4)
        point d'arrêt/point à surveiller matériels

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

    CLD_EXITED
        fils terminé normalement

    CLD_KILLED
        fils tué par un signal

    CLD_DUMPED
        fils terminé anormalement

    CLD_TRAPPED
        fils en cours de suivi

    CLD_STOPPED
        fils arrêté

    CLD_CONTINUED
        fils arrêté a redémarré (depuis Linux 2.6.9)

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

    POLL_IN
        données disponibles en entrée

    POLL_OUT
        tampons de sortie libres

    POLL_MSG
        message disponible en entrée

    POLL_ERR
        erreur d'entrée-sortie

    POLL_PRI
        entrée haute priorité disponible

    POLL_HUP
        périphérique débranché

VALEUR RENVOYÉE
sigaction() renvoie 0 s'il réussit, et -1 en cas d'erreur.

ERREURS

EFAULT
    act ou oldact pointent en-dehors de l'espace d'adressage accessible.

EINVAL
    Un signal invalide est indiqué. Ceci se produit également si l'on tente de modifier l'action associée aux signaux SIGKILL ou SIGSTOP, qui ne peuvent pas être interceptés ou ignorés.

CONFORMITÉ
POSIX.1-2001, SVr4.

NOTES
Un fils créé par fork(2) hérite d'une copie des dispositions de signaux de son père. Lors d'un execve(2), les dispositions des signaux pris en charge sont remises aux valeurs par défaut ; les dispositions des signaux ignorés ne sont pas modifiées. Comme spécifié par POSIX, le comportement d'un processus est indéfini après la réception d'un signal SIGFPE, SIGILL, ou SIGSEGV qui n'a pas été engendré par une fonction kill(2) ou raise(3). La division entière par zéro a un résultat indéfini, sur certaines architectures elle déclenche un signal SIGFPE. De même, diviser l'entier le plus négatif par -1 peut déclencher SIGFPE.

POSIX.1-1990 interdisait d'ignorer SIGCHLD avec SIG_IGN. POSIX.1-2001 l'autorise, et ignorer SIGCHLD permet donc d'éviter la création de zombies (consultez wait(2)). Cependant, les comportements historiques de BSD et de System V quand SIGCHLD est ignoré diffèrent, donc la seule méthode complètement portable pour s'assurer que les fils ne deviennent pas des zombies à leur terminaison est d'intercepter le signal SIGCHLD et d'invoquer wait(2) ou équivalent.

POSIX.1-1990 ne documentait que SA_NOCLDSTOP. POSIX.1-2001 a ajouté SA_NOCLDWAIT, SA_RESETHAND, SA_NODEFER et SA_SIGINFO. L'utilisation de ces dernières valeurs dans sa_flags peut être moins portable dans les applications censées s'exécuter sur des implémentations UNIX anciennes.

L'option SA_RESETHAND est compatible avec l'option SVr4 du même nom.

L'option SA_NODEFER est compatible avec l'option SVr4 du même nom pour les noyaux 1.3.9 et ultérieurs. Pour les noyaux plus anciens, Linux autorisera la réception de tous les signaux et pas seulement celui qui vient de se déclencher (écrasant effectivement sa_mask ).

sigaction() peut être appelé avec un second argument à NULL pour obtenir le gestionnaire de signaux actuel. On peut aussi vérifier si un signal est valide sur la machine actuelle en l'appelant avec les deuxième et troisième arguments qui valent NULL.

Il est impossible de bloquer SIGKILL or SIGSTOP (en les indiquant dans sa_mask). Les tentatives seront ignorées silencieusement.

Consultez sigsetops(3) pour les détails concernant les ensembles de signaux.

Consultez signal(7) pour une liste de fonctions sûres pour les signaux asynchrones qui peuvent être appelée dans les gestionnaires de signaux.

  Non documenté
Avant l'introduction de l'attribut SA_SIGINFO il était déjà possible d'obtenir des informations supplémentaires, en ajoutant au sa_handler un second paramètre de type struct sigcontext. On peut retrouver ceci dans les sources du noyau. Ce mécanisme est désormais obsolète.

BOGUES
Dans les noyaux jusqu'à 2.6.13 inclus, indiquer SA_NODEFER dans sa_flags empêchait non seulement le signal reçu d'être masqué pendant l'exécution du gestionnaire, mais empêchait également les signaux de sa_mask d'être masqués. Ce bogue a été corrigé dans Linux 2.6.14.

EXEMPLE
Consultez mprotect(2).

VOIR AUSSI
kill(1), kill(2), killpg(2), pause(2), sigaltstack(2), signal(2), signalfd(2), sigpending(2), sigprocmask(2), sigsuspend(2), wait(2), raise(3), siginterrupt(3), sigqueue(3), sigsetops(3), sigvec(3), core(5), signal(7)

COLOPHON
Cette page fait partie de la publication 3.40 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <URL:http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <URL:http://perkamon.alioth.debian.org/>.

Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».