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);
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 fichier à surveiller est indiqué dans
l’argument fds, qui est un tableau de structures de la forme suivante :
struct pollfd {
int fd; /* Descripteur de fichier */
short events; /* Événements attendus */
short revents; /* Événements détectés */
};
L’appelant doit spécifier le nombre d’élément du tableau fds dans nfds.
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, d’un des types
demandés par events, 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(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
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().
Si le paramètre sigmask est défini comm NULL, aucune manipulation de
masque de signaux n’est effectuée (et ainsi ppoll() ne diffère de
poll() que dans la précision du paramètre timeout).
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
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 Linux 2.6.16. La fonction
de bibliothèque 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 timeout. Cette constante
n’est pas fournie par la glibc.
Notes sur 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).
VOIR AUSSI
select(2), select_tut(2), feature_test_macros(7), time(7)
COLOPHON
Cette page fait partie de la publication 3.23 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/.
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> ».