Provided by: manpages-fr-dev_4.13-4_all bug

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  ou  une
              profondeur d'arborescence d'instances epoll plus importante que 5.

       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 dans la version 2.6. La prise en charge par la glibc a
       été ajoutée à partir de la version 2.3.2.

CONFORMITÉ

       epoll_ctl() est spécifique à Linux.

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.10 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  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  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 ⟨⟩.