epoll_ctl
Section: System Calls (2)
Updated: 4 décembre 2022
Index
Return to Main Contents
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
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 à
Index
- NOM
-
- BIBLIOTHÈQUE
-
- SYNOPSIS
-
- DESCRIPTION
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- VERSIONS
-
- STANDARDS
-
- NOTES
-
- BOGUES
-
- VOIR AUSSI
-
- TRADUCTION
-
This document was created by
man2html,
using the manual pages.
Time: 05:59:27 GMT, May 23, 2024