POLL(2)

NOM
poll, ppoll - Attendre un événement concernant un descripteur de fichier

SYNOPSIS
#include <poll.h>

int poll(struct pollfd *fds, nfds_t nfds, int délai);

#define _GNU_SOURCE
#include <poll.h>

int ppoll(struct pollfd *fds, nfds_t nfds,
        const struct timespec *délai, const sigset_t *sigmask);

DESCRIPTION
poll() est une variation de select(2) : il attend que l'un des descripteurs de fichier parmi un ensemble soit prêt pour effectuer des entrées-sorties. L'ensemble des descripteurs de fichier à surveiller est indiqué dans l'argument fds qui est un tableau de structures nfds du type :
struct pollfd {
    int   fd;         /* Descripteur de fichier */
    short events;     /* Événements attendus    */
    short revents;    /* Événements détectés    */
};
Le champ fd contient un descripteur de fichier ouvert. Le champ events est un paramètre d'entrée, un masque de bits indiquant les événements qui intéressent l'application. Le champ revents est un paramètre de sortie, rempli par le noyau avec les événements qui se sont effectivement produits. Les bits renvoyés dans revents peuvent inclure ceux spécifiés dans events, ou l'une des valeurs POLLERR, POLLHUP ou POLLNVAL. (Ces trois bits n'ont pas de signification dans la demande events, et se trouvent positionnés dans la valeur de retour revents si l'une des conditions correspondantes se produit.) Si aucun événement attendu (ni aucune erreur) ne s'est déjà produit, poll() bloque jusqu'à ce que l'un des événements survienne. L'argument délai définit une limite supérieure, en millisecondes, sur le temps pendant lequel poll() bloquera. Définir une valeur négative pour délai signifie un délai d'attente infini. Les bits qui peuvent être positionnés ou renvoyés dans events et revents sont définis dans <poll.h> :

    POLLIN
        Il y a des données en attente de lecture.

    POLLPRI
        Il y a des données urgentes en attente de lecture (par exemple, des données « hors bande » sur une socket TCP ; un pseudo-terminal maître en mode paquet a vu l'esclave changer d'état).

    POLLOUT
        Une écriture ne bloquera pas.

    POLLRDHUP (depuis Linux 2.6.17)
        Le correspondant sur une socket en mode flux a fermé la connexion, ou bien a été mis hors service lors de l'écriture sur la connexion. La macro de test de fonctionnalité _GNU_SOURCE doit être définie pour obtenir cette définition.

    POLLERR
        Condition d'erreur (uniquement en sortie).

    POLLHUP
        Déconnexion (uniquement en sortie).

    POLLNVAL
        Requête invalide : fd n'est pas ouvert (uniquement en sortie).

Lorsque _XOPEN_SOURCE est définie à la compilation, les macros suivantes sont également définies mais n'apportent pas plus d'information que les bits précédents :

    POLLRDNORM
        Équivalent à POLLIN.

    POLLRDBAND
        Des données prioritaires sont en attente de lecture (généralement pas utilisé sous Linux).

    POLLWRNORM
        Équivalent à POLLOUT.

    POLLWRBAND
        Des données prioritaires peuvent être écrites.

Linux connaît également POLLMSG mais ne l'utilise pas.

  ppoll()
La relation entre poll() et ppoll() est analogue à la relation entre select(2) et pselect(2) : de même que pselect(2), ppoll() permet à une application d'attendre de façon sûre que soit un descripteur de fichier devienne prêt, soit un signal soit capturé.

Outre la différence de l'argument délai, l'appel ppoll() suivant :
    ready = ppoll(&fds, nfds, timeout, &sigmask);
est équivalent à l'exécution atomique des appels suivants :
    sigset_t origmask;
    sigprocmask(SIG_SETMASK, &sigmask, &origmask);
    ready = poll(&fds, nfds, timeout);
    sigprocmask(SIG_SETMASK, &origmask, NULL);

Voir la description de pselect(2) pour une explication de la nécessité de ppoll(). Si l'argument sigmask est défini comme NULL, aucune manipulation de masque de signaux n'est effectuée (et ainsi ppoll() ne diffère de poll() que dans la précision de l'argument timeout). L'argument timeout définit une limite supérieure sur le temps total pendant lequel ppoll() bloquera. Cet argument est un pointeur sur une structure de la forme :
struct timespec {
    long    tv_sec;         /* secondes */
    long    tv_nsec;        /* nanosecondes */
};
Si timeout est NULL, bloquera indéfiniment.

VALEUR RENVOYÉE
S'ils réussissent, ces appels renvoient une valeur positive représentant le nombre de structures ayant un champ revents non nul, c'est-à-dire le nombre de structures pour lesquels un événement attendu, ou une erreur, s'est produit. Une valeur de retour nulle indique un dépassement du délai d'attente et qu'aucun descripteur de fichier n'était prêt. S'ils échouent, ces appels renvoient -1, et errno contient le code d'erreur.

ERREURS

EBADF
    Un descripteur de fichier invalide est présent dans un ensemble.

EFAULT
    La table fournie en argument n'est pas dans l'espace d'adressage du processus appelant.

EINTR
    Un signal a été reçu avant qu'un événement intéressant ne se produise ; voir signal(7).

EINVAL
    La valeur nfds dépasse la valeur RLIMIT_NOFILE.

ENOMEM
    Pas assez de mémoire pour allouer la table des descripteurs de fichier.

VERSIONS
L'appel système poll() a été introduit dans la version 2.1.23 du noyau Linux. La fonction de bibliothèque poll() est apparue dans la version 5.4.28 de la libc, et fournit une émulation basée sur l'appel système select(2) si le noyau n'a pas d'appel système poll(). L'appel système ppoll() a été introduit à dans le noyau Linux 2.6.16. La fonction de bibliothèque ppoll() correspondante a été ajoutée dans la glibc 2.4

CONFORMITÉ
poll() est conforme à POSIX.1-2001. ppoll() est spécifique à Linux.

NOTES
Certaines implémentations définissent la constante symbolique non standard INFTIM de valeur -1 à utiliser comme délai. Cette constante n'est pas fournie par la glibc.

  Notes Linux
L'appel système ppoll() sous Linux modifie son argument délai. Toutefois, la fonction enveloppe de la glibc cache ce comportement en utilisant une variable locale pour l'argument délai qui est passée à l'appel système. La fonction ppoll() de la glibc ne modifie donc pas son argument délai.

BOGUES
Voir la discussion sur les notifications indésirées dans la section BOGUES de select(2).

VOIR AUSSI
select(2), select_tut(2), feature_test_macros(7), time(7)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 21 juillet 1997 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 poll ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.