.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2006, 2019 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" Additions from Richard Gooch and aeb, 971207 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\" formatting changes. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH POLL 2 "11 avril 2020" Linux "Manuel du programmeur Linux" .SH NOM poll, ppoll \- Attendre un événement concernant un descripteur de fichier .SH SYNOPSIS .nf \fB#include \fP .PP \fBint poll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, int \fP\fItimeout\fP\fB);\fP \fB#define _GNU_SOURCE\fP /* Consultez feature_test_macros(7) */ \fB#include \fP \fB#include \fP .PP \fBint ppoll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB,\fP \fB const struct timespec *\fP\fItmo_p\fP\fB, const sigset_t *\fP\fIsigmask\fP\fB);\fP .fi .SH DESCRIPTION \fBpoll\fP() fait la même chose que \fBselect\fP(2)\ : il attend que l'un des descripteurs de fichier soit prêt pour des entrées et sorties. L'API de \fBepoll\fP(7) spécifique à Linux fait la même chose, mais avec des fonctionnalités allant au\-delà de celles de \fBpoll\fP(). .PP L'ensemble de descripteurs de fichier à surveiller est indiqué dans l'argument \fIfds\fP qui est un tableau de structures de la forme suivante\ : .PP .in +4n .EX struct pollfd { int fd; /* Descripteur de fichier */ short events; /* Événements attendus */ short revents; /* Événements détectés */ }; .EE .in .PP L'appelant doit spécifier le nombre d'éléments du tableau \fIfds\fP dans \fInfds\fP. .PP Le champ \fIfd\fP contient un descripteur de fichier pour un fichier ouvert. Si ce champ est négatif, alors le champ \fIevents\fP correspondant est ignoré et le champ \fIrevents\fP renvoie zéro (cela permet d'ignorer facilement un descripteur de fichier pour un seul appel \fBpoll\fP()\ : il suffit d'utiliser l'opposé du champ \fIfd\fP\ ; remarquez cependant que cette technique ne peut pas être utilisée pour ignorer le descripteur de fichier \fB0\fP). .PP Le champ \fIevents\fP 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 \fIfd\fP. Ce champ peut être nul, auquel cas les seuls événements qui peuvent être renvoyés dans \fIrevents\fP sont \fBPOLLHUP\fP, \fBPOLLERR\fP et \fBPOLLNVAL\fP (voir ci\-dessous). .PP Le champ \fIrevents\fP 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 \fIevents\fP ou de l'une des valeurs \fBPOLLERR\fP, \fBPOLLHUP\fP ou \fBPOLLNVAL\fP. (Ces trois bits n'ont pas de signification dans la demande \fIevents\fP et se trouvent positionnés dans la valeur de retour \fIrevents\fP si l'une des conditions correspondantes se produit.) .PP Si aucun événement attendu (ni aucune erreur) ne s'est déjà produit, \fBpoll\fP() bloque jusqu'à ce que l'un des événements se produise. .PP L'argument \fItimeout\fP définit le temps en milliseconde pendant lequel \fBpoll\fP() devrait bloquer en attendant que le descripteur de fichier soit prêt. L’appel bloquera jusqu’au premier événement suivant\ : .IP " \(bu" 2 un descripteur de fichier devient prêt\ ; .IP " \(bu" l’appel est interrompu par un gestionnaire de signal\ ; .IP " \(bu" le délai expire. .PP Remarquez que l’intervalle \fItimeout\fP 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 \fItimeout\fP signifie un délai infini, alors qu'un \fItimeout\fP nul force \fBepoll\fP() à se terminer immédiatement, même si aucun descripteur de fichier n'est prêt. .PP Les bits qui peuvent être activés ou renvoyés dans \fIevents\fP et \fIrevents\fP sont définis par \fI\fP\ : .TP \fBPOLLIN\fP Il y a des données en attente de lecture. .TP \fBPOLLPRI\fP Il existe une condition d'exception sur le descripteur de fichier. Parmi celles possibles\ : .RS .IP " \(bu" 2 Des données dépassent sur un socket TCP (voir \fBtcp\fP(7)). .IP " \(bu" Un pseudoterminal maître en mode paquet a vu un changement d'état sur l'esclave (voir \fBioctl_tty\fP(2)). .IP " \(bu" Un fichier \fIcgroup.events\fP a été modifié (voir \fBcgroups\fP(7)). .RE .TP \fBPOLLOUT\fP L'écriture est maintenant possible, mais une écriture plus grande que l'espace disponible sur un socket ou un tube bloquera encore (sauf si \fBO_NONBLOCK\fP est positionné). .TP \fBPOLLRDHUP\fP (depuis Linux 2.6.17) Le correspondant sur un socket en mode flux a fermé la connexion ou bien a terminé la partie écriture de la connexion. La macro de test de fonctionnalité \fB_GNU_SOURCE\fP doit être définie (avant d'inclure \fItout\fP fichier d'en\(hytête) pour obtenir cette définition. .TP \fBPOLLERR\fP Condition d'erreur (renvoyée seulement dans \fIrevents\fP\ ; ignorée dans \fIevents\fP). Ce bit est aussi positionné pour un descripteur de fichier qui se rapporte à une fin d'écriture sur un tube lorsque la fin de lecture a été fermée. .TP \fBPOLLHUP\fP Plantage (renvoyé seulement dans \fIrevents\fP\ ; ignoré dans \fIevents\fP). Remarquez qu'en lecture à partir d'un canal tel qu'un tube ou un socket de flux, cet événement indique simplement que le pair a fermé la fin de son canal. Les lectures suivantes à partir du canal ne renverront \fB0\fP (fin de fichier) qu'après que toutes les données du canal aient été consommées. .TP \fBPOLLNVAL\fP Requête non valable\ : \fIfd\fP n'est pas ouvert (renvoyé seulement dans \fIrevents\fP\ ; ignoré dans \fIevents\fP). .PP Lorsque \fB_XOPEN_SOURCE\fP 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\(hydessus\ : .TP \fBPOLLRDNORM\fP Équivalent à \fBPOLLIN\fP. .TP \fBPOLLRDBAND\fP .\" POLLRDBAND is used in the DECnet protocol. Des données prioritaires sont en attente de lecture (généralement inutilisé sous Linux). .TP \fBPOLLWRNORM\fP Équivalent à \fBPOLLOUT\fP. .TP \fBPOLLWRBAND\fP Des données prioritaires peuvent être écrites. .PP Linux connaît aussi \fBPOLLMSG\fP, mais ne l'utilise pas. .SS ppoll() La relation entre \fBpoll\fP() et \fBppoll\fP() est similaire à la relation entre \fBselect\fP(2) et \fBpselect\fP(2)\ : comme \fBpselect\fP(2), \fBppoll\fP() 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. .PP Mise à part la différence de précision de l'argument \fItimeout\fP, l'appel \fBppoll\fP() suivant\ : .PP .in +4n .EX ready = ppoll(&fds, nfds, tmo_p, &sigmask); .EE .in .PP est presque équivalent à exécuter de façon \fIatomique\fP les appels suivants\ : .PP .in +4n .EX sigset_t origmask; int timeout; timeout = (tmo_p == NULL) ? \-1 : (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); ready = poll(&fds, nfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in .PP Le bout de code ci\-dessus est décrit comme \fIpresque\fP équivalent parce qu’une valeur négative dans \fI*tmo_p\fP donne une erreur de \fBppoll\fP(), tandis qu’une valeur négative de \fItimeout\fP pour \fBpoll\fP() est interprétée comme un délai infini. .PP Consultez la description de \fBpselect\fP(2) pour une explication de la nécessité de \fBppoll\fP(). .PP Si le paramètre \fIsigmask\fP est défini comme NULL, aucune manipulation de masque de signaux n'est effectuée (et ainsi \fBppoll\fP() ne diffère de \fBpoll\fP() que dans la précision du paramètre \fItimeout\fP). .PP L'argument \fItmo_p\fP définit une limite supérieure sur le temps pendant lequel \fBppoll\fP() bloquera. Cet argument est un pointeur vers une structure de la forme suivante\ : .PP .in +4n .EX struct timespec { long tv_sec; /* secondes */ long tv_nsec; /* nanosecondes */ }; .EE .in .PP Si \fItmo_p\fP est NULL, \fBppoll\fP() pourra bloquer indéfiniment. .SH "VALEUR RENVOYÉE" En cas de succès, \fBpoll\fP() renvoie une valeur non négative qui est un nombre d'éléments dans \fIpollfds\fP dont les champs \fIrevents\fP ont été positionnés sur une autre valeur que zéro (indiquant un événement ou une erreur). Un code de retour de zéro indique que l'appel système a atteint son délai avant qu'un descripteur de fichier ne soit lu. .PP En cas d'erreur, la valeur de retour est \fB\-1\fP et \fIerrno\fP est définie pour indiquer la cause de l'erreur. .SH ERREURS .TP \fBEFAULT\fP \fIfds\fP pointe hors de l'espace d'adressage accessible. Le tableau donné en argument ne se trouvait pas dans l'espace d'adressage du programme appelant. .TP \fBEINTR\fP Un signal a été reçu avant qu'un événement intéressant ne se produise\ ; voir \fBsignal\fP(7). .TP \fBEINVAL\fP La valeur \fInfds\fP dépasse la valeur \fBRLIMIT_NOFILE\fP. .TP \fBEINVAL\fP (\fBppoll\fP()) La valeur du délai exprimée dans \fI*ip\fP n'est pas valable (négative). .TP \fBENOMEM\fP Impossible d'allouer de la mémoire pour des structures de données du noyau. .SH VERSIONS L'appel système \fBpoll\fP() a été introduit dans Linux\ 2.1.23. Sur les anciens noyaux sans cet appel système, la fonction enveloppe \fBpoll\fP() de la glibc fournit une émulation en utilisant \fBselect\fP(2). .PP L'appel système \fBppoll\fP() a été introduit dans Linux\ 2.6.16. La fonction de bibliothèque correspondante a été ajoutée dans la glibc\ 2.4. .SH CONFORMITÉ .\" FIXME . .\" ppoll() is proposed for inclusion in POSIX: .\" https://www.austingroupbugs.net/view.php?id=1263 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). \fBpoll\fP() est conforme à POSIX.1\-2001 et POSIX.1\-2008. \fBppoll\fP() est spécifique à Linux. .SH NOTES L'opération de \fBpoll\fP() et \fBppoll\fP() n'est pas concernée par l'attribut \fBO_NONBLOCK\fP. .PP .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett Sur d'autres systèmes UNIX, \fBpoll\fP() peut échouer avec l'erreur \fBEAGAIN\fP si le système n'arrive pas à allouer des ressources internes au noyau, et non avec \fBENOMEM\fP comme sur Linux. POSIX autorise ce comportement. Les programmes portables peuvent vouloir vérifier \fBEAGAIN\fP et tourner en boucle, comme avec \fBEINTR\fP. .PP Certaines implémentations définissent la constante symbolique non standard \fBINFTIM\fP de valeur \fB\-1\fP, à utiliser comme \fItimeout\fP pour \fBpoll\fP(). Cette constante n'est pas fournie par la glibc. .PP Consultez \fBselect\fP(2) pour une discussion sur ce qui pourrait arriver si un descripteur de fichier surveillé par \fBpoll\fP() est fermé dans un autre thread. .SS "différences entre bibliothèque C et noyau" L'appel système \fBppoll\fP() sous Linux modifie son argument \fItmo_p\fP. Cependant, l'enveloppe fournie par la glibc cache ce comportement en utilisant une variable locale pour le délai qui est fournie à l'appel système. Ainsi, la fonction \fBppoll\fP() de la glibc ne modifie donc pas son argument \fItmo_p\fP. .PP L'appel système \fBppoll\fP() brut a un cinquième paramètre, \fIsize_t sigsetsize\fP, qui indique la taille en octets du paramètre \fIsigmask\fP. La fonction enveloppe \fBppoll\fP() de la glibc indique ce paramètre comme une valeur fixe (égale à \fIsizeof(kernel_sigset_t)\fP). Voir \fBsigprocmask\fP(2) pour un point sur les différences entre l'approche du noyau et de la libc de sigset. .SH BOGUES Consultez la discussion sur les notifications non voulues dans la section BOGUES de \fBselect\fP(2). .SH EXEMPLES Le programme ci\-dessous ouvre chacun des fichiers nommés sur ses paramètres de la ligne de commande et surveille les descripteurs de fichier qui en résultent quand à leur possibilité d'être lus (\fBPOLLIN\fP). Le programme effectue une boucle de \fBpoll\fP() pour surveiller les descripteurs de fichier, affichant en retour le nombre de descripteurs de fichier prêts. Pour chaque descripteur disponible, le programme\ : .IP " \(bu" 2 affiche le champ \fIrevents\fP renvoyé sous une forme lisible par un humain\ ; .IP " \(bu" si le descripteur de fichier est lisible, y lit des données et affiche ces données sur la sortie standard\ ; et .IP " \(bu" si le descripteur de fichier n'était pas lisible mais qu'un autre événement s'est produit (probablement \fBPOLLHUP\fP), ferme le descripteur de fichier. .PP Supposons qu'on lance le programme dans un terminal, en lui demandant d'ouvrir un FIFO\ : .PP .in +4n .EX $ \fBmkfifo monfifo\fP $ \fB./poll_input monfifo\fP .EE .in .PP Dans une deuxième fenêtre de terminal, on ouvre alors le FIFO en écriture, on y écrit des données et on ferme le FIFO\ : .PP .in +4n .EX $ \fBecho aaaaabbbbbccccc > monfifo\fP .EE .in .PP Dans le terminal où on exécute le programme, on verrait alors\ : .PP .in +4n .EX "monfifo" ouvert sur le fd 3 Préparation pour poll() Prêt\ : 1 fd=3\ ; événements: POLLIN POLLHUP 10 octets lus\ : aaaaabbbbb Va poll() Prêt\ : 1 fd=3\ ; événements\ : POLLIN POLLHUP lecture de 6 octets\ : ccccc Préparation pour poll() Prêt\ : 1 fd=3\ ; événements\ : POLLHUP fermeture de fd 3 Tous les descripteurs de fichier sont fermés\ ; au revoir .EE .in .PP Dans la sortie ci\-dessus, on voit que \fBpoll\fP() a renvoyé trois fois\ : .IP " \(bu" 2 Sur le premier retour, les bits renvoyés dans le champ \fIrevents\fP étaient \fBPOLLIN\fP, indiquant que le descripteur de fichier est lisible, et \fBPOLLHUP\fP, indiquant que l'autre extrémité du FIFO a été fermée. Puis le programme a consommé une partie de l'entrée disponible. .IP " \(bu" Le deuxième retour de \fBpoll\fP() indiquait aussi \fBPOLLIN\fP et \fBPOLLHUP\fP\ ; le programme a alors consommé la dernière partie de l’entrée disponible. .IP " \(bu" .\" Sur le dernier retour, \fBpoll\fP() n'indiquait que \fBPOLLHUP\fP sur le FIFO, lemoment où le descripteur de fichier a été fermé et où le programme s'est terminé. .SS "Source du programme" \& .EX /* poll_input.c Sous licence GNU General Public License v2 ou postérieure. */ #include #include #include #include #include #include #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e } while (0) int main(int argc, char *argv[]) { int nfds, num_open_fds; struct pollfd *pfds; if (argc < 2) { fprintf(stderr, "Utilisation\ : %s fichier...\en", argv[0]); exit(EXIT_FAILURE); } num_open_fds = nfds = argc \- 1; pfds = calloc(nfds, sizeof(struct pollfd)); if (pfds == NULL) errExit("malloc"); /* Ouvrir chaque fichier de la ligne de commande et l'ajouter au tableau \(aqpfds\(aq */ for (int j = 0; j < nfds; j++) { pfds[j].fd = open(argv[j + 1], O_RDONLY); if (pfds[j].fd == \-1) errExit("open"); printf("\e"%s\e" ouvert sur le fd %d\en", argv[j + 1], pfds[j].fd); pfds[j].events = POLLIN; } /* Conserver poll() au moins aussi longtemps qu'un descripteur de fichier est ouvert */ while (num_open_fds > 0) { int ready; printf("Va poll()\en"); ready = poll(pfds, nfds, \-1); if (ready == \-1) errExit("poll"); printf("Prêt\ : %d\en", ready); /* Gérer le tableau renvoyé par poll() */ for (int j = 0; j < nfds; j++) { char buf[10]; if (pfds[j].revents != 0) { printf(" fd=%d\ ; événements\ : %s%s%s\en", pfds[j].fd, (pfds[j].revents & POLLIN) ? "POLLIN " : "", (pfds[j].revents & POLLHUP) ? "POLLHUP " : "", (pfds[j].revents & POLLERR) ? "POLLERR " : ""); if (pfds[j].revents & POLLIN) { ssize_t s = read(pfds[j].fd, buf, sizeof(buf)); if (s == \-1) errExit("read"); printf(" lecture de %zd octets\ : %.*s\en", s, (int) s, buf); } else { /* POLLERR | POLLHUP */ printf(" fermeture du fd %d\en", pfds[j].fd); if (close(pfds[j].fd) == \-1) errExit("close"); num_open_fds\-\-; } } } } printf("Tous les descripteurs de fichier sont fermés\ ; au revoir\en"); exit(EXIT_SUCCESS); } .EE .SH "VOIR AUSSI" \fBrestart_syscall\fP(2), \fBselect\fP(2), \fBselect_tut\fP(2), \fBepoll\fP(7), \fBtime\fP(7) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Jean-Philippe MENGUAL . Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .