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 /* Consultez feature_test_macros(7) */
#include <poll.h>
int ppoll(struct pollfd *fds, nfds_t nfds,
const struct timespec *timeout_ts, 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 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 un descripteur de fichier pour un fichier ouvert. Si
ce champ est négatif, alors le champ
events correspondant est
ignoré et le champ
revents renvoie zéro (cela permet
d'ignorer facilement un descripteur de fichier pour un seul appel
poll() : il suffit d'utiliser l'opposé du champ
fd).
Le champ
events est un paramètre d'entrée, un masque de
bits indiquant les événements qui intéressent
l'application pour le descripteur de fichier
fd. Ce champ peut
être nul, auquel cas les seuls événements qui peuvent
être renvoyés dans
revents sont
POLLHUP,
POLLERR et
POLLNVAL (voir ci-dessous).
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 le temps en milliseconde pendant lequel
poll() devrait bloquer en attendant que le descripteur de fichier soit
prêt. L’appel bloquera jusqu’au premier
événement suivant :
- *
- un descripteur de fichier devient prêt ;
- *
- l’appel est interrompu par un gestionnaire de signal ;
- *
- le délai expire.
Remarquez que l’intervalle
timeout sera arrondi à la
granularité de l'horloge système et que les délais
d'ordonnancement du noyau signifient que l'intervalle de blocage pourrait
être dépassé d'une petite quantité. Une valeur
négative de
timeout signifie un délai infini, alors qu'un
timeout nul force
epoll() à se terminer
immédiatement, même si aucun descripteur de fichier n'est
prêt.
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 pseudoterminal
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 (avant d'inclure tout fichier
d'en‐tête) 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.
Mise à part la différence de précision de l'argument
timeout, l'appel
ppoll() suivant :
ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
est équivalent à exécuter de façon
atomique
les appels suivants :
sigset_t origmask;
int timeout;
timeout = (timeout_ts == NULL) ? -1 :
(timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
sigprocmask(SIG_SETMASK, &sigmask, &origmask);
ready = poll(&fds, nfds, timeout);
sigprocmask(SIG_SETMASK, &origmask, NULL);
Consultez la description de
pselect(2) pour une explication de la
nécessité de
ppoll().
Si le paramètre
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
du paramètre
timeout).
L'argument
timeout_ts 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_ts 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
Linux 2.1.23. Sur les anciens noyaux sans cet appel système, la
fonction enveloppe
poll() de la glibc (et de l'ancienne libc Linux)
fournit une émulation en utilisant
select(2).
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.
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
pour
poll(). Cette constante n'est pas fournie par la glibc.
Consultez
select(2) pour une discussion sur ce qui pourrait arriver si un
descripteur de fichier surveillé par
poll() est fermé
dans un autre thread.
Notes sur Linux¶
L'appel système
ppoll() sous Linux modifie son argument
timeout_ts. 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_ts.
BOGUES¶
Consultez la discussion sur les notifications non voulues dans la section BOGUES
de
select(2).
VOIR AUSSI¶
restart_syscall(2),
select(2),
select_tut(2),
time(7)
COLOPHON¶
Cette page fait partie de la publication 3.65 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¶
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/>.
Christophe Blaess <
http://www.blaess.fr/christophe/> (1996-2003), Alain
Portal <
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 à
<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> ».