Linux Certif

Toute la documentation sur la certification Linux LPI

Rechercher une page de manuel

poll

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 timeout);
 
 #define _GNU_SOURCE
 #include <poll.h>
 
 int ppoll(struct pollfd *fds, nfds_t nfds, 
  const struct timespec *timeout, const sigset_t *sigmask);
 

DESCRIPTION

poll() est une variation sur le thème de select(2) : il attend que l'un des descripteurs de fichier soit prêt pour des entrées-sorties.

L'ensemble de descripteurs de fichiers à surveiller est indiqué dans l'argument fds, qui est un tableau de nfds structures 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 le descripteur d'un 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, du type demandé, ou de 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 se produise.

L'argument timeout définit une limite supérieure pour le temps pendant lequel poll() attendra, en millisecondes. Une valeur négative de timeout indique un délai infini.

Les bits qui peuvent être activés ou renvoyés dans events et revents sont définis par <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, ou bien un pseudo-terminal maître en mode paquet constatant un changement d'état de l'esclave).

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 terminé la partie écriture de 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

Le correspondant a fermé la connexion (uniquement en sortie).

POLLNVAL

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

Lorsque _XOPEN_SOURCE est défini à la compilation, les macros suivantes sont également définies (mais n'apportent pas d'informations supplémentaires par rapport aux bits listés ci-dessus :

POLLRDNORM

Équivalent à POLLIN.

POLLRDBAND

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

POLLWRNORM

Équivalent à POLLOUT.

POLLWRBAND

Des données prioritaires peuvent être écrites.

Linux connaît aussi POLLMSG, mais ne l'utilise pas.

ppoll()

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

À part la différence liée à l'argument timeout, l'appel ppoll() suivant :

 
     ready = ppoll(&fds, nfds, timeout, &sigmask);
 
 

est équivalent à exécuter de façon atomique les 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().

L'argument timeout définit une limite supérieure sur le temps pendant lequel ppoll() bloquera. Cet argument est pointe vers une structure de la forme suivante :

 
 struct timespec {
     long    tv_sec;         /* secondes     */
     long    tv_nsec;        /* nanosecondes */
 };
 

Si timeout est NULL, ppoll() pourra bloquer indéfiniment.

VALEUR RENVOYÉE

En cas de réussite, 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. En cas d'échec, ils renvoient -1, et errno contient le code d'erreur.

ERREURS

EBADF

Un descripteur de fichier (dans l'un des ensembles) est invalide.

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.

EINVAL

La valeur nfds dépasse la valeur RLIMIT_NOFILE.

ENOMEM

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

SPÉCIFICITÉS LINUX

L'appel système ppoll() sous Linux modifie son argument timeout. Cependant, l'enrobage fourni par la glibc cache ce comportement en utilisant une variable locale pour le délai, qui est fournie à l'appel système. La fonction ppoll() de la glibc ne modifie donc pas son argument timeout.

BOGUES

Voir la discussion sur les notifications non voulues dans la section BOGUES de select(2).

CONFORMITÉ

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

HISTORIQUE

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() si le noyau n'a pas d'appel système poll().

L'appel système ppoll() a été introduit dans Linux 2.6.16. La fonction de bibliothèque correspondante a été ajoutée dans la glibc 2.4.

NOTES

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

VOIR AUSSI

select(2), select_tut(2), feature_test_macros(7)

TRADUCTION

Cette page de manuel a été traduite et mise à jour par Christophe Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par Alain Portal <aportal AT univ-montp2 DOT fr> jusqu'en 2006, et mise à disposition sur http://manpagesfr.free.fr/.

Les mises à jour et corrections de la version présente dans Debian sont directement gérées par Julien Cristau <jcristau@debian.org> et l'équipe francophone de traduction de Debian.

Veuillez signaler toute erreur de traduction en écrivant à <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le paquet manpages-fr.

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