Man page 2 : signalfd

signalfd - Créer un descripteur de fichier pour accepter des signaux

#include <sys/signalfd.h>

int signalfd(int fd, const sigset_t *mask, int flags);

signalfd() crée un descripteur de fichier qui peut être utilisé pour accepter des signaux à destination de l'appelant. Ceci fournit une alternative à l'utilisation d'un gestionnaire de signal ou de sigwaitinfo(2), et a l'avantage que le descripteur de fichier peut être surveillé avec select(2), poll(2) ou epoll(7). Le paramètre mask spécifie l'ensemble des signaux que l'appelant veut accepter par le descripteur de fichier. Ce paramètre est un ensemble de signaux dont le contenu peut être initialisé en utilisant les macros décrites dans sigsetops(3). Normalement, l'ensemble des signaux reçus par le descripteur de fichier devrait être bloqués en utilisant sigprocmask(2) pour éviter que les signaux soient pris en charge par les gestionnaires par défaut. Il n'est pas possible de recevoir les signaux SIGKILL ou SIGSTOP par un descripteur de fichier signalfd ; ces signaux sont ignorés sans rien dire s'ils sont spécifiés dans mask. Si le paramètre fd vaut -1, l'appel crée un nouveau descripteur de fichier et associe l'ensemble des signaux spécifiés dans mask avec ce descripteur. Si fd ne vaut pas -1, alors il doit indiquer un descripteur de fichier signalfd existant valable, et mask est utilisé pour remplacer l'ensemble des signaux associés avec ce descripteur. À partir de Linux 2.6.27, les valeurs suivantes peuvent être incluses avec un OU binaire dans flags pour changer le comportement de signalfd() :

• SFD_NONBLOCK
                Placer l'attribut d'état de fichier O_NONBLOCK sur le nouveau descripteur de fichier ouvert. Utiliser cet attribut économise des appels supplémentaires à fcntl(2) pour obtenir le même résultat.
• SFD_CLOEXEC
      Placer l'attribut « close-on-exec » (FD_CLOEXEC) sur le nouveau descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2) pour savoir pourquoi cela peut être utile.

Dans les versions de Linux jusqu'à la version 2.6.26, le paramètre flags n'est pas utilisé et doit valoir zéro. signalfd() renvoie un descripteur de fichier qui gère les opérations suivantes :

• read(2)
      Si un (ou plus) des signaux spécifiés dans mask est en attente pour le processus, alors le tampon fourni à read(2) est utilisé pour renvoyer une structure (ou plus) de type signalfd_siginfo (voir ci-dessous) qui décrit les signaux. read(2) renvoie les informations pour tous les signaux qui sont en attente et qui tiennent dans le tampon fourni. Le tampon doit avoir une taille d'au moins sizeof(struct signalfd_siginfo) octets. La valeur de retour de read(2) est égale au nombre total d'octets lus.

En conséquence du read(2), les signaux sont consommés, de telle sorte qu'ils ne seront plus en attente pour le processus (c'est-à-dire qu'ils ne seront plus attrapés par les gestionnaires de signaux, et ne seront plus acceptés par sigwaitinfo(2)).

Si aucun des signaux de mask ne sont en attente pour le processus, read(2) sera bloquera jusqu'à ce qu'un des signaux de mask soit généré pour le processus, ou échouera avec l'erreur EAGAIN si le descripteur de fichier est en mode non bloquant.

• poll(2), select(2) (et similaires)
      Le descripteur de fichier est lisible (le paramètre readfds de select(2) ; l'attribut POLLIN de poll(2)) si un signal ou plus de mask est en attente pour le processus.

Le descripteur de fichier signalfd gère également les autres interfaces de multiplexage de descripteurs de fichier : pselect(2), ppoll(2) et epoll(7).

• close(2)
      Quand le descripteur de fichier n'est plus nécessaire il doit être fermé. Quand tous les descripteurs de fichier associés au même objet signalfd ont été fermés, les ressources pour cet objet sont libérées par le noyau.

3.1. La structure signalfd_siginfo ▲

struct signalfd_siginfo {
    uint32_t ssi_signo;   /* Numéro de signal */
    int32_t  ssi_errno;   /* Numéro d'erreur (pas utilisé) */
    int32_t  ssi_code;    /* Code du signal */
    uint32_t ssi_pid;     /* PID de l'émetteur */
    uint32_t ssi_uid;     /* UID réel de l'émetteur */
    int32_t  ssi_fd;      /* Descripteur de fichier (SIGIO) */
    uint32_t ssi_tid;     /* Identifiant de la temporisation
                             du noyau (timers POSIX) */
    uint32_t ssi_band;    /* Événement de bande (SIGIO) */
    uint32_t ssi_overrun; /* Compte des dépassements de la
                             temporisation POSIX */
    uint32_t ssi_trapno;  /* Numéro de trappe ayant causé le signal */
    int32_t  ssi_status;  /* Code de sortie ou signal (SIGCHLD) */
    int32_t  ssi_int;     /* Entier envoyé par sigqueue(3) */
    uint64_t ssi_ptr      /* Pointeur envoyé par sigqueue(3) */
    uint64_t ssi_utime;   /* Temps CPU utilisateur consommé (SIGCHLD) */
    uint64_t ssi_stime;   /* Temps CPU système consommé (SIGCHLD) */
    uint64_t ssi_addr;    /* Adresse qui a généré le signal
                             (pour les signaux issu du matériel) */
    uint8_t  pad[X];      /* Remplissage jusqu'à 128 octets
                             (espace prévu pour des champs
                             supplémentaires futurs) */
};

3.2. Sémantique de fork(2) ▲

3.3. Sémantique de execve(2) ▲

3.4. Sémantique des threads ▲

S'il réussit, signalfd() renvoie un descripteur de fichier signalfd ; il s'agit soit d'un nouveau descripteur de fichier (si fd valait -1), ou fd si fd était un descripteur de fichier signalfd valable. En cas d'erreur, il renvoie -1 et errno contient le code d'erreur.

• EBADF
      Le descripteur de fichier fd n'est pas un descripteur de fichier valable.
• EINVAL fd n'est pas un descripteur de fichier signalfd valable.
• EINVAL
      flags n'est pas correct ; ou, pour les versions de Linux 2.6.26 ou ultérieures, flags n'est pas nul.
• EMFILE
      La limite du nombre total de descripteurs de fichier ouverts par processus a été atteinte.
• ENFILE
      La limite du nombre total de fichiers ouverts sur le système a été atteinte.
• ENODEV
      Impossible de monter (en interne) le périphérique anonyme d'inœud.
• ENOMEM
      Pas assez de mémoire pour créer le descripteur de fichier signalfd.

signalfd() est disponible sous Linux depuis le noyau 2.6.22. La glibc le gère depuis la version 2.8. L'appel système signalfd4() (voir NOTES) est disponible sous Linux depuis le noyau 2.6.27.

signalfd() et signalfd4() sont spécifiques à Linux.

L'appel système Linux sous-jacent nécessite un paramètre supplémentaire, size_t sizemask, qui spécifie la taille du paramètre mask. La fonction enveloppe signalfd() de la glibc n'a pas ce paramètre, puisqu'elle fournit ce paramètre à l'appel système sous-jacent. Un processus peut créer plusieurs descripteurs de fichier signalfd. Ceci permet d'accepter différents signaux sur différents descripteurs de fichier (et peut être utile si les descripteurs de fichier sont surveillés en utilisant select(2), poll(2) ou epoll(7) : l'arrivée de différents signaux rendra différents descripteurs de fichier disponibles). Si un signal apparaît dans le mask de plusieurs descripteurs de fichier, un signal reçu pourra être lu (une seule fois) depuis n'importe lequel des descripteurs.

8.1. Appels système Linux sous-jacents ▲

Dans les noyaux antérieurs à 2.6.25, les champs ssi_ptr et ssi_int n'étaient pas renseignés avec les données accompagnant un signal envoyé par sigqueue(3).

Le programme ci-dessous accèpte les signaux SIGINT et SIGQUIT en utilisant un descripteur de fichier signalfd. Le programme se termine après avoir accepté le signal SIGQUIT. La session shell suivante montre l'utilisation du programme :

$ ./signalfd_demo
^C                   # Contrôle-C génère un SIGINT
Got SIGINT
^C
Got SIGINT
^\                    # Contrôle-\ génère un SIGQUIT
Got SIGQUIT
$

10.1. Source du programme ▲

#include <sys/signalfd.h>
#include <signal.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{
    sigset_t mask;
    int sfd;
    struct signalfd_siginfo fdsi;
    ssize_t s;
    sigemptyset(&mask);
    sigaddset(&mask, SIGINT);
    sigaddset(&mask, SIGQUIT);
    /* Bloquer les signaux pour qu'il ne soit plus géré
       par les gestionnaires par défaut */
    if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)
        handle_error("sigprocmask");
    sfd = signalfd(-1, &mask, 0);
    if (sfd == -1)
        handle_error("signalfd");
    for (;;) {
        s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
        if (s != sizeof(struct signalfd_siginfo))
            handle_error("read");
        if (fdsi.ssi_signo == SIGINT) {
            printf("Got SIGINT\n");
        } else if (fdsi.ssi_signo == SIGQUIT) {
            printf("Got SIGQUIT\n");
            exit(EXIT_SUCCESS);
        } else {
            printf("Read unexpected signal\n");
        }
    }
}

eventfd(2), poll(2), read(2), select(2), sigaction(2), sigprocmask(2), sigwaitinfo(2), timerfd_create(2), sigsetops(3), sigwait(3), epoll(7), signal(7)

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

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

Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <>.

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