EPOLL_CTL(2)

NOM
epoll_ctl - Interface de contrôle pour un descripteur epoll

SYNOPSIS
#include <sys/epoll.h>

int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

DESCRIPTION
Cet appel système effectue des opérations de contrôle sur l'instance epoll(7) référencée par le 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
    Enregistre le descripteur de fichier cible fd pour l'instance epoll indiquée par le descripteur de fichier epfd et associe l'événement event avec le fichier représenté par fd.

EPOLL_CTL_MOD
    Change l'événement event associé au descripteur de fichier fd.

EPOLL_CTL_DEL
    Supprime (désenregistre) le descripteur de fichier fd de l'instance epoll indiquée par epfd. 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 structure 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 events est un masque de bits composé à partir des événements disponibles suivants :

EPOLLIN
    Le descripteur associé est disponible pour un appel read(2).

EPOLLOUT
    Le descripteur associé est disponible pour un appel write(2).

EPOLLRDHUP (depuis Linux 2.6.17)
    Le correspondant sur une socket en mode flux a fermé la connexion, ou bien a terminé la partie écriture de la connexion. (Cet attribut est particulièrement utile pour écrire du code simple permettant de détecter la fermeture de la connexion par le correspondant en détection de changement d'état.)

EPOLLPRI
    Il y a des données urgentes disponibles pour un appel read(2).

EPOLLERR
    Une erreur s'est produite sur le descripteur de fichier associé. epoll_wait(2) attend toujours cet événement, il n'est pas nécessaire de l'indiquer dans events.

EPOLLHUP
    Une déconnexion s'est produite sur le descripteur associé. epoll_wait(2) attend toujours cet événement, il n'est pas nécessaire de l'indiquer dans events.

EPOLLET
    Définir le comportement en détection de changement d'état sur le descripteur. 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)
    Définir le comportement « coup unique » (Ndt : one-shot) pour le descripteur de fichier associé. Cela signifie qu'après qu'un événement a été retiré avec epoll_wait(2), le descripteur de fichier est désactivé de manière interne 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). Consultez également BOGUES

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 contient le code approprié.

ERREURS

EBADF
    epfd ou fd n'est pas un descripteur de fichier valable.

EEXIST
    op est EPOLL_CTL_ADD, mais le descripteur de fichier fd est déjà enregistrée 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 supportée par cette interface.

ENOENT
    op est EPOLL_CTL_MOD ou EPOLL_CTL_DEL, et fd n'est 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 fichier cible fd n'est pas supporté par epoll.

VERSIONS
epoll_ctl() a été ajouté au noyau Linux dans sa version 2.6.

CONFORMITÉ
epoll_ctl() est spécifique à Linux. La prise en charge par la glibc a été ajoutée dans la version 2.3.2.

NOTES
L'interface epoll supporte tous les descripteurs de fichier supporté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 3.70 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».