epoll_ctl(2) System Calls Manual epoll_ctl(2)
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éra-
tion 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 fi-
chier epoll epfd. L'entrée comprend le descripteur de fichier,
fd, une référence à la description du fichier ouvert correspon-
dant (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 com-
posé 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 dispo-
nibles 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 fi-
chier. Voir le point sur POLLPRI dans poll(2).
EPOLLERR
Une condition d’erreur s'est produite sur le descripteur de fi-
chier 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 simple-
ment que le correspondant a fermé sa partie de canal. Les lec-
tures qui suivent issues du canal ne renverront 0 (fin de fi-
chier) 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 compor-
tements 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 descrip-
teur 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 des-
cripteur 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 fi-
chier 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 évi-
ter 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 EPOLLEXCLU-
SIVE : 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 signa-
lés s'ils arrivent, qu'ils soient ou non indiqués dans events.
Les tentatives d'indiquer d'autres valeurs dans events pro-
voquent 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 EPOLLEXCLU-
SIVE 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é ap-
pliqué 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 enre-
gistré 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 bi-
bliothè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 Li-
nux 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é si-
lencieusement. Ce comportement malheureux est nécessaire parce qu’au-
cune 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 ca-
pacité 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 capa-
cité CAP_BLOCK_SUSPEND avant d’essayer d’utiliser l’attribut EPOLLWA-
KEUP.
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 Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.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.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.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⟩.
Pages du manuel de Linux 6.03 4 décembre 2022 epoll_ctl(2)
Generated by dwww version 1.15 on Sat Jun 29 01:47:04 CEST 2024.