epoll_ctl - Interface de contrôle pour un descripteur de
fichier epoll
#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int
fd, struct epoll_event *event);
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).
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é.
- 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.
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.
epoll_ctl() est spécifique à Linux.
L'interface epoll prend en charge tous les descripteurs de
fichier gérés par poll(2).
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.
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/.
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.