Provided by: manpages-fr-dev_4.15.0-9_all 
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 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 à
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.13 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⟩.