epoll_ctl - Interface de contrôle pour un descripteur de fichier epoll
Bibliothèque C standard (
libc,
-lc)
#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *_Nullable 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é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.
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.
- 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.
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.
epoll_ctl() est spécifique à Linux.
L'interface
epoll prend en charge tous les descripteurs de fichier
gérés par
poll(2).
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.
epoll_create(2),
epoll_wait(2),
poll(2),
epoll(7)
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]>, David Prévot <
[email protected]> et
Jean-Philippe MENGUAL <
[email protected]>
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 à
[email protected]