Provided by: manpages-fr-dev_4.21.0-2_all bug

NOM

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

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <sys/epoll.h>

       int epoll_ctl(int epfd, int op, int fd, struct epoll_event *_Nullable 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écrite dans epoll_event(3type).

       Le  membre  data  de  la  structure  epoll_event  indique  les  données  que le noyau doit
       enregistrer et renvoyer (à l’aide de 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 une
       opération OU sur zéro ou plusieurs des types d'événements renvoyés  par  epoll_wait(2)  et
       les  attributs  d'entrée,  qui  modifient son comportement, mais ne sont pas renvoyés. Les
       types d'événements disponibles sont :

       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.

       Et les attributs d'entrée disponibles sont :

       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.

       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.

       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.

       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 bousculade (thundering herd) dans certains scénarii.

              Si un même descripteur de fichier est  dans  plusieurs  instances  epoll,  certains
              ayant  l'attribut  EPOLLEXCLUSIVE  et 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.

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 est positionné pour indiquer l'erreur.

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 à
              cette 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é dans Linux 2.6. La prise en charge de la bibliothèque est fournie
       dans la glibc 2.3.2.

STANDARDS

       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

       Avant  Linux 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 à Linux 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)

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⟩.