epoll_ctl(2) System Calls Manual epoll_ctl(2) NOM epoll_ctl - Interface de controle pour un descripteur de fichier epoll BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include int epoll_ctl(int epfd, int op, int fd, struct epoll_event *_Nullable event); DESCRIPTION Cet appel systeme est utilise pour ajouter, modifier ou supprimer des entrees dans la liste des interets d'une instance epoll(7) a laquelle se rapporte un descripteur de fichier epfd. Il necessite que l'operation op soit effectuee sur le descripteur de fichier cible fd. Les valeurs autorisees pour le parametre op sont : EPOLL_CTL_ADD Ajouter une entree a la liste d'interets du descripteur de fichier epoll epfd. L'entree comprend le descripteur de fichier, fd, une reference a la description du fichier ouvert correspondant (voir epoll(7) et open(2)), et les parametres indiques dans event. EPOLL_CTL_MOD Passer les parametres associes a fd dans la liste des interets a ceux specifies dans event. EPOLL_CTL_DEL Supprimer (desenregistrer) le descripteur de fichier cible fd de la liste d'interets. Le parametre event est ignore et peut etre NULL (mais consultez la section BOGUES ci-dessous). Le parametre event decrit l'objet lie au descripteur de fichier fd. La struct epoll_event est decrite dans epoll_event(3type). Le membre data de la structure epoll_event indique les donnees que le noyau doit enregistrer et renvoyer (a l'aide de epoll_wait(2)) quand ce descripteur de fichier est pret. Le membre events de la structure epoll_event est un masque de bits compose par une operation OU sur zero ou plusieurs des types d'evenements renvoyes par epoll_wait(2) et les attributs d'entree, qui modifient son comportement, mais ne sont pas renvoyes. Les types d'evenements disponibles sont : EPOLLIN Le fichier associe est disponible pour un appel read(2). EPOLLOUT Le fichier associe est disponible pour un appel write(2). EPOLLRDHUP (depuis Linux 2.6.17) Le correspondant sur un socket en mode flux a ferme la connexion, ou bien a termine d'ecrire a la moitie de la connexion. (Cet attribut est particulierement utile pour ecrire du code simple permettant de detecter la fermeture de la connexion par surveillance du changement d'etat). EPOLLPRI Il existe une condition exceptionnelle sur le descripteur de fichier. Voir le point sur POLLPRI dans poll(2). EPOLLERR Une condition d'erreur s'est produite sur le descripteur de fichier associe. Cet evenement est aussi signale pour la partie ecriture d'un tube (pipe) lorsque la partie lecture a ete arretee. epoll_wait(2) signalera toujours cet evenement, il n'est pas necessaire de l'indiquer dans events lors d'un appel epoll_ctl(). EPOLLHUP Un blocage s'est produit sur le descripteur de fichier associe. epoll_wait(2) signalera toujours cet evenement, il n'est pas necessaire de l'indiquer dans events lors d'un appel a epoll_ctl(). Remarquez que lors d'une lecture a partir d'un canal tel qu'un tube (pipe) ou un socket de flux, cet evenement indique simplement que le correspondant a ferme sa partie de canal. Les lectures qui suivent issues du canal ne renverront 0 (fin de fichier) qu'apres que toutes les donnees restantes dans le canal aient ete consommees. Et les attributs d'entree disponibles sont : EPOLLET Demande les notifications par changement d'etat du descripteur de fichier associe. Par defaut epoll fonctionne en detection de niveau. Consultez epoll(7) pour plus de details sur les comportements en detection de niveau et de changements d'etat. EPOLLONESHOT (depuis Linux 2.6.2) Demande une notification en << coup unique >> (Ndt : one-shot) pour le descripteur de fichier associe. Cela signifie qu'apres qu'un evenement a ete notifie par epoll_wait(2) pour le descripteur de fichier, celui-ci est desactive de la liste d'interets et aucun autre evenement ne sera rapporte par l'interface epoll. L'utilisateur doit appeler epoll_ctl() avec EPOLL_CTL_MOD pour rearmer le descripteur de fichier avec le nouveau masque d'evenement. EPOLLWAKEUP (depuis Linux 3.5) Si EPOLLONESHOT et EPOLLET sont vides et que le processus a la capacite CAP_BLOCK_SUSPEND, s'assurer que le systeme n'entre pas en << veille >> ou << hibernation >> pendant que cet evenement est en attente ou en train d'etre traite. L'evenement est considere << traite >> a partir du moment ou il est renvoye, par un appel d'epoll_wait(2) avant le prochain appel d'epoll_wait(2) sur le meme descripteur de fichier epoll(7), la fermeture de ce descripteur de fichier, la suppression du descripteur de fichier de l'evenement avec EPOLL_CTL_DEL, ou le vidage de EPOLLWAKEUP pour le descripteur de fichier de l'evenement avec EPOLL_CTL_MOD. Consultez egalement BOGUES. EPOLLEXCLUSIVE (depuis Linux 4.5) Definit un mode de reveil exclusif pour le descripteur de fichier epoll qui va etre attache au descripteur de fichier cible, fd. Quand un evenement de reveil se produit et que plusieurs descripteurs de fichier epoll sont rattaches au meme fichier cible en utilisant EPOLLEXCLUSIVE, un ou plusieurs descripteurs de fichier epoll recevront un evenement avec epoll_wait(2). Le comportement par defaut dans ce scenario (quand EPOLLEXCLUSIVE n'est pas defini) est que tous les descripteurs de fichier epoll recoivent un evenement. EPOLLEXCLUSIVE est ainsi utile pour eviter des problemes de bousculade (thundering herd) dans certains scenarii. Si un meme descripteur de fichier est dans plusieurs instances epoll, certains ayant l'attribut EPOLLEXCLUSIVE et d'autres pas, les evenements seront fournis a toutes les instances epoll qui n'ont pas indique EPOLLEXCLUSIVE et a au moins une des instances epoll ou EPOLLEXCLUSIVE est indique. Les valeurs suivantes peuvent etre indiquees avec EPOLLEXCLUSIVE : EPOLLIN, EPOLLOUT, EPOLLWAKEUP et EPOLLET. EPOLLHUP et EPOLLERR peuvent egalement etre indiques mais cela n'est pas necessaire : comme d'habitude, ces evenements sont toujours signales s'ils arrivent, qu'ils soient ou non indiques dans events. Les tentatives d'indiquer d'autres valeurs dans events provoquent l'erreur EINVAL. EPOLLEXCLUSIVE ne peut etre utilise que dans une operation EPOLL_CTL_ADD ; les tentatives de l'utiliser avec EPOLL_CTL_MOD provoquent une erreur. Si EPOLLEXCLUSIVE a ete positionne en utilisant epoll_ctl(), le EPOLL_CTL_MOD consecutif sur la meme paire epfd, fd provoque une erreur. Un appel a epoll_ctl() qui indique EPOLLEXCLUSIVE dans events et le descripteur de fichier cible fd en instance epoll echouera probablement. Dans tous ces cas, l'erreur est EINVAL. VALEUR RENVOYEE Lorsqu'il reussit, l'appel epoll_ctl() renvoie zero. Si une erreur se produit, epoll_ctl() renvoie -1 et errno est positionne pour indiquer l'erreur. ERREURS EBADF epfd ou fd n'est pas un descripteur de fichier valable. EEXIST op etait EPOLL_CTL_ADD, mais le descripteur de fichier fd est deja enregistre dans cette instance epoll. EINVAL Le descripteur de fichier epfd, n'est pas un descripteur epoll, ou fd et epfd sont identiques, ou l'operation demandee op n'est pas geree par cette interface. EINVAL Un type d'evenement non valable a ete indique avec EPOLLEXCLUSIVE dans events. EINVAL op valait EPOLL_CTL_MOD et events comprenait un EPOLLEXCLUSIVE. EINVAL op valait EPOLL_CTL_MOD et le drapeau EPOLLEXCLUSIVE a ete applique precedemment a cette paire epfd, fd. EINVAL EPOLLEXCLUSIVE etait indique dans event et fd se rapporte a une instance epoll. ELOOP fd se rapporte a une instance epoll et cette operation EPOLL_CTL_ADD creerait une boucle infinie d'instances epoll qui se surveilleraient mutuellement ou une profondeur d'arborescence d'instances epoll plus importante que 5. ENOENT op etait EPOLL_CTL_MOD ou EPOLL_CTL_DEL, et fd n'etait pas enregistre dans cette instance epoll. ENOMEM Pas assez de memoire dans le noyau pour traiter l'operation op demandee. ENOSPC La limite imposee par /proc/sys/fs/epoll/max_user_watches a ete rencontree en essayant d'enregistrer (EPOLL_CTL_ADD), un nouveau descripteur de fichier, sur une instance epoll. Consultez epoll(7) pour plus de details. EPERM Le ficher cible fd ne prend pas en charge epoll. Cette erreur peut arriver si fd renvoie, par exemple, a un fichier ou a un repertoire regulier. STANDARDS Linux. HISTORIQUE Linux 2.6, glibc 2.3.2. NOTES L'interface epoll prend en charge tous les descripteurs de fichier geres par poll(2). BOGUES Avant Linux 2.6.9, l'operation EPOLL_CTL_DEL necessitait un pointeur non NULL dans event, alors que ce parametre est ignore. Depuis Linux 2.6.9, event peut etre NULL lors d'une operation EPOLL_CTL_DEL. Les applications qui doivent etre portables pour les noyaux anterieurs a Linux 2.6.9 devraient utiliser un pointeur different de NULL dans event. Si EPOLLWAKEUP est indique dans flags, mais que l'appelant n'a pas la capacite CAP_BLOCK_SUSPEND, alors l'attribut EPOLLWAKEUP est ignore silencieusement. Ce comportement malheureux est necessaire parce qu'aucune verification de validite n'etait realisee sur l'argument flags dans l'implementation d'origine, et l'ajout du EPOLLWAKEUP avec une verification forcant l'echec de l'appel si l'appelant n'avait pas la capacite CAP_BLOCK_SUSPEND cassait au moins une application en espace utilisateur qui indiquait aleatoirement (et inutilement) ce bit. Une application robuste devrait donc verifier a deux fois d'avoir la capacite CAP_BLOCK_SUSPEND avant d'essayer d'utiliser l'attribut EPOLLWAKEUP. VOIR AUSSI epoll_create(2), epoll_wait(2), poll(2), epoll(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 epoll_ctl(2)