epoll_ctl

EPOLL_CTL(2)               Manuel du programmeur Linux              EPOLL_CTL(2)



NOM
       epoll_ctl - Interface de contrôle pour un descripteur de fichier epoll

SYNOPSIS
       #include <sys/epoll.h>

       int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

DESCRIPTION
       Cet appel système est utilisé pour ajouter, modifier ou supprimer des
       entrées dans la liste des intérêts d'une instance epoll(7) à laquelle se
       rapporte un descripteur de fichier epfd. Il nécessite que l'opération op
       soit effectuée sur le descripteur de fichier cible fd.

       Les valeurs autorisées pour le paramètre op sont :

       EPOLL_CTL_ADD
              Ajouter une entrée à la liste d'intérêts du descripteur de fichier
              epoll epfd. L'entrée comprend le descripteur de fichier, fd, une
              référence à la description du fichier ouvert correspondant (voir
              epoll(7) et open(2)) et les paramètres indiqués dans event.

       EPOLL_CTL_MOD
              Passer les paramètres associés à fd dans la liste des intérêts à
              ceux spécifiés dans event.

       EPOLL_CTL_DEL
              Supprimer (désenregistrer) le descripteur de fichier cible fd de
              la liste d'intérêts. Le paramètre event est ignoré et peut être
              NULL (mais consultez la section BOGUES ci‐dessous).

       Le paramètre event décrit l'objet lié au descripteur de fichier fd. La
       struct epoll_event est définie ainsi :

           typedef union epoll_data {
               void        *ptr;
               int          fd;
               uint32_t     u32;
               uint64_t     u64;
           } epoll_data_t;

           struct epoll_event {
               uint32_t events;        /* Événements epoll     */
               epoll_data_t data;      /* Variable utilisateur */
           };

       Le membre data de la structure epoll_event indique les données que le
       noyau doit enregistrer et renvoyer (via epoll_wait(2)) quand ce
       descripteur de fichier est prêt.

       Le membre events de la structure epoll_event est un masque de bits
       composé par un OU et zéro ou plusieurs des types d'événements disponibles
       suivants :

       EPOLLIN
              Le fichier associé est disponible pour un appel read(2).

       EPOLLOUT
              Le fichier associé est disponible pour un appel write(2).

       EPOLLRDHUP (depuis Linux 2.6.17)
              Le correspondant sur un socket en mode flux a fermé la connexion,
              ou bien a terminé d’écrire à la moitié de la connexion. (Cet
              attribut est particulièrement utile pour écrire du code simple
              permettant de détecter la fermeture de la connexion par
              surveillance du changement d’état.

       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 associé. Cet événement est aussi signalé pour la partie
              écriture d’un tube (pipe) lorsque la partie lecture a été arrêtée.

              epoll_wait(2) signalera toujours cet événement, il n'est pas
              nécessaire de l'indiquer dans events lors d'un appel epoll_ctl().

       EPOLLHUP
              Un blocage s'est produit sur le descripteur de fichier associé.

              epoll_wait(2) signalera toujours cet événement, il n'est pas
              nécessaire de l'indiquer dans events lors d'un appel epoll_ctl().

              Remarquez que lors d'une lecture à partir d'un canal tel qu'un
              tube (pipe) ou un socket de flux, cet événement indique simplement
              que le correspondant a fermé sa partie de canal. Les lectures qui
              suivent issues du canal ne renverront 0 (fin de fichier) qu'après
              que toutes les données restantes dans le canal aient été
              consommées.

       EPOLLET
              Demande les notifications par changement d’état du descripteur de
              fichier associé. Par défaut epoll fonctionne en détection de
              niveau. Consultez epoll(7) pour plus de détails sur les
              comportements en détection de niveau et de changements d'état.

              Cet drapeau est un drapeau d'entrée du champ event.events lors
              d'un appel à epoll_ctl() ; il n'est jamais renvoyé par
              epoll_wait(2).

       EPOLLONESHOT (depuis Linux 2.6.2)
              Demande une notification en « coup unique » (Ndt : one‐shot) pour
              le descripteur de fichier associé. Cela signifie qu'après qu'un
              événement a été notifié par epoll_wait(2) pour le descripteur de
              fichier, celui-ci est désactivé de la liste d'intérêts et aucun
              autre événement ne sera rapporté par l'interface epoll.
              L'utilisateur doit appeler epoll_ctl() avec EPOLL_CTL_MOD pour
              réarmer le descripteur de fichier avec le nouveau masque
              d'événement.

              Cet drapeau est un drapeau d'entrée du champ event.events lors
              d'un appel à epoll_ctl() ; il n'est jamais renvoyé par
              epoll_wait(2).

       EPOLLWAKEUP (depuis Linux 3.5)
              Si EPOLLONESHOT et EPOLLET sont vides et que le processus a la
              capacité CAP_BLOCK_SUSPEND, s’assurer que le système n’entre pas
              en « veille » ou « hibernation » pendant que cet événement est en
              attente ou en train d’être traité. L’événement est considéré
              « traité » à partir du moment où il est renvoyé, par un appel
              d’epoll_wait(2) avant le prochain appel d’epoll_wait(2) sur le
              même descripteur de fichier epoll(7), la fermeture de ce
              descripteur de fichier, la suppression du descripteur de fichier
              de l'événement avec EPOLL_CTL_DEL, ou le vidage de EPOLLWAKEUP
              pour le descripteur de fichier de l'événement avec EPOLL_CTL_MOD.
              Consultez également BOGUES.

              Cet drapeau est un drapeau d'entrée du champ event.events lors
              d'un appel à epoll_ctl() ; il n'est jamais renvoyé par
              epoll_wait(2).

       EPOLLEXCLUSIVE (depuis Linux 4.5)
              Définit un mode de réveil exclusif pour le descripteur de fichier
              epoll qui va être attaché au descripteur de fichier cible, fd.
              Quand un événement de réveil se produit et que plusieurs
              descripteurs de fichier epoll sont rattachés au même fichier cible
              en utilisant EPOLLEXCLUSIVE, un ou plusieurs descripteurs de
              fichier epoll recevront un événement avec epoll_wait(2). Le
              comportement par défaut dans ce scénario (quand EPOLLEXCLUSIVE
              n'est pas défini) est que tous les descripteurs de fichier epoll
              reçoivent un événement. EPOLLEXCLUSIVE est ainsi utile pour éviter
              des problèmes de « thundering herd » dans certains scénari.

              Si un même descripteur de fichier est dans plusieurs instances
              epoll, certains ayant l'attribut EPOLLEXCLUSIVE, d'autres pas, les
              événements seront fournis à toutes les instances epoll qui n'ont
              pas indiqué EPOLLEXCLUSIVE et à au moins une des instances epoll
              où EPOLLEXCLUSIVE est indiqué.

              Les valeurs suivantes peuvent être indiquées avec EPOLLEXCLUSIVE :
              EPOLLIN, EPOLLOUT, EPOLLWAKEUP et EPOLLET. EPOLLHUP et EPOLLERR
              peuvent également être indiqués mais cela n'est pas nécessaire :
              comme d'habitude, ces événements sont toujours signalés s'ils
              arrivent, qu'ils soient ou non indiqués dans events. Les
              tentatives d'indiquer d'autres valeurs dans events provoquent
              l'erreur EINVAL.

              EPOLLEXCLUSIVE ne peut être utilisé que dans une opération
              EPOLL_CTL_ADD ; les tentatives de l'utiliser avec EPOLL_CTL_MOD
              provoquent une erreur. Si EPOLLEXCLUSIVE a été positionné en
              utilisant epoll_ctl(), le EPOLL_CTL_MOD consécutif sur la même
              paire epfd, fd provoque une erreur. Un appel à epoll_ctl() qui
              indique EPOLLEXCLUSIVE dans events et le descripteur de fichier
              cible fd en instance epoll échouera probablement. Dans tous ces
              cas, l'erreur est EINVAL.

              Le drapeau EPOLLEXCLUSIVE est un drapeau d'entrée du champ
              event.events lors d'un appel à epoll_ctl() ; il n'est jamais
              renvoyé par epoll_wait(2).

VALEUR RENVOYÉE
       Lorsqu'il réussit, l'appel epoll_ctl() renvoie zéro. Si une erreur se
       produit, epoll_ctl() renvoie -1 et errno contient le code approprié.

ERREURS
       EBADF  epfd ou fd n'est pas un descripteur de fichier valable.

       EEXIST op était EPOLL_CTL_ADD, mais le descripteur de fichier fd est déjà
              enregistré dans cette instance epoll.

       EINVAL Le descripteur de fichier epfd, n'est pas un descripteur epoll, ou
              fd et epfd sont identiques, ou l'opération demandée op n'est pas
              gérée par cette interface.

       EINVAL Un type d'événement non valable a été indiqué 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 été
              appliqué précédemment à la paire epfd, fd.

       EINVAL EPOLLEXCLUSIVE était indiqué dans event et fd se rapporte à une
              instance epoll.

       ELOOP  fd se rapporte à une instance epoll et cette opération
              EPOLL_CTL_ADD créerait une boucle infinie d'instances epoll qui se
              surveilleraient mutuellement.

       ENOENT op était EPOLL_CTL_MOD ou EPOLL_CTL_DEL, et fd n'était pas
              enregistré dans cette instance epoll.

       ENOMEM Pas assez de mémoire dans le noyau pour traiter l'opération op
              demandée.

       ENOSPC La limite imposée par /proc/sys/fs/epoll/max_user_watches a été
              rencontrée en essayant d'enregistrer (EPOLL_CTL_ADD) un nouveau
              descripteur de fichier sur une instance epoll. Consultez epoll(7)
              pour plus de détails.

       EPERM  Le ficher cible fd ne prend pas en charge epoll. Cette erreur peut
              arriver si fd renvoie, par exemple, à un fichier ou à un
              répertoire régulier.

VERSIONS
       epoll_ctl() a été ajouté au noyau Linux dans sa version 2.6.

CONFORMITÉ
       epoll_ctl() est spécifique à Linux. La prise en charge par la glibc a été
       ajoutée dans la version 2.3.2.

NOTES
       L'interface epoll prend en charge tous les descripteurs de fichier gérés
       par poll(2).

BOGUES
       Dans les versions du noyau antérieures à 2.6.9, l'opération EPOLL_CTL_DEL
       nécessitait un pointeur non NULL dans event, alors que ce paramètre est
       ignoré. Depuis Linux 2.6.9, event peut être NULL lors d'une opération
       EPOLL_CTL_DEL. Les applications qui doivent être portables pour les
       noyaux antérieurs à 2.6.9 devraient utiliser un pointeur différent de
       NULL dans event.

       Si EPOLLWAKEUP est indiqué dans flags, mais que l’appelant n’a pas la
       capacité CAP_BLOCK_SUSPEND, alors l’attribut EPOLLWAKEUP est ignoré
       silencieusement. Ce comportement malheureux est nécessaire parce
       qu’aucune vérification de validité n’était réalisée sur l’argument flags
       dans l’implémentation d’origine, et l’ajout du EPOLLWAKEUP avec une
       vérification forçant l’échec de l’appel si l’appelant n’avait pas la
       capacité CAP_BLOCK_SUSPEND cassait au moins une application en espace
       utilisateur qui indiquait aléatoirement (et inutilement) ce bit. Une
       application robuste devrait donc vérifier à deux fois d’avoir la capacité
       CAP_BLOCK_SUSPEND avant d’essayer d’utiliser l’attribut EPOLLWAKEUP.

VOIR AUSSI
       epoll_create(2), epoll_wait(2), poll(2), epoll(7)

COLOPHON
       Cette page fait partie de la publication 5.08 du projet man-pages 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/.


TRADUCTION
       La traduction française de cette page de manuel a été créée par
       Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin
       <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>,
       François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe
       Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
       luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas
       Huriaux <thomas.huriaux@gmail.com>, Nicolas François
       <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>,
       Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier
       <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Philippe
       MENGUAL <jpmengual@debian.org>

       Cette traduction est une documentation libre ; veuillez vous reporter à
       la GNU General Public License version 3 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 à <debian-l10n-french@lists.debian.org>.



Linux                             11 avril 2020                     EPOLL_CTL(2)