.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2003 Davide Libenzi .\" Davide Libenzi .\" and Copyright 2009, 2014, 2016, 2018, 2019 Michael Kerrisk .\" .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH EPOLL_CTL 2 "1 novembre 2020" Linux "Manuel du programmeur Linux" .SH NOM epoll_ctl \- Interface de contrôle pour un descripteur de fichier epoll .SH SYNOPSIS \fB#include \fP .PP \fBint epoll_ctl(int \fP\fIepfd\fP\fB, int \fP\fIop\fP\fB, int \fP\fIfd\fP\fB, struct epoll_event *\fP\fIevent\fP\fB);\fP .SH 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 \fBepoll\fP(7) à laquelle se rapporte un descripteur de fichier \fIepfd\fP. Il nécessite que l'opération \fIop\fP soit effectuée sur le descripteur de fichier cible \fIfd\fP. .PP Les valeurs autorisées pour le paramètre \fIop\fP sont\ : .TP \fBEPOLL_CTL_ADD\fP Ajouter une entrée à la liste d'intérêts du descripteur de fichier epoll \fIepfd\fP. L'entrée comprend le descripteur de fichier, \fIfd\fP, une référence à la description du fichier ouvert correspondant (voir \fBepoll\fP(7) et \fBopen\fP(2)), et les paramètres indiqués dans \fIevent\fP. .TP \fBEPOLL_CTL_MOD\fP Passer les paramètres associés à \fIfd\fP dans la liste des intérêts à ceux spécifiés dans \fIevent\fP. .TP \fBEPOLL_CTL_DEL\fP Supprimer (désenregistrer) le descripteur de fichier cible \fIfd\fP de la liste d'intérêts. Le paramètre \fIevent\fP est ignoré et peut être NULL (mais consultez la section BOGUES ci\(hydessous). .PP Le paramètre \fIevent\fP décrit l'objet lié au descripteur de fichier \fIfd\fP. La \fIstruct epoll_event\fP est définie ainsi\ : .PP .in +4n .EX 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 */ }; .EE .in .PP Le membre \fIdata\fP de la structure \fIepoll_event\fP indique les données que le noyau doit enregistrer et renvoyer (à l’aide de \fBepoll_wait\fP(2)) quand ce descripteur de fichier est prêt. .PP Le membre \fIevents\fP de la structure \fIepoll_event\fP est un masque de bits composé par une opération OU sur zéro ou plusieurs des types d'événements disponibles suivants\ : .TP \fBEPOLLIN\fP Le fichier associé est disponible pour un appel \fBread\fP(2). .TP \fBEPOLLOUT\fP Le fichier associé est disponible pour un appel \fBwrite\fP(2). .TP \fBEPOLLRDHUP\fP (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). .TP \fBEPOLLPRI\fP Il existe une condition exceptionnelle sur le descripteur de fichier. Voir le point sur \fBPOLLPRI\fP dans \fBpoll\fP(2). .TP \fBEPOLLERR\fP 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. .IP \fBepoll_wait\fP(2) signalera toujours cet événement, il n'est pas nécessaire de l'indiquer dans \fIevents\fP lors d'un appel \fBepoll_ctl\fP(). .TP \fBEPOLLHUP\fP Un blocage s'est produit sur le descripteur de fichier associé. .IP \fBepoll_wait\fP(2) signalera toujours cet événement, il n'est pas nécessaire de l'indiquer dans \fIevents\fP lors d'un appel à \fBepoll_ctl\fP(). .IP 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 \fB0\fP (fin de fichier) qu'après que toutes les données restantes dans le canal aient été consommées. .TP \fBEPOLLET\fP Demande les notifications par changement d’état du descripteur de fichier associé. Par défaut \fBepoll\fP fonctionne en détection de niveau. Consultez \fBepoll\fP(7) pour plus de détails sur les comportements en détection de niveau et de changements d'état. .IP Cet drapeau est un drapeau d'entrée du champ \fIevent.events\fP lors d'un appel à \fBepoll_ctl\fP()\ ; il n'est jamais renvoyé par \fBepoll_wait\fP(2). .TP \fBEPOLLONESHOT\fP (depuis Linux 2.6.2) Demande une notification en «\ coup unique\ » (Ndt\ : one\(hyshot) pour le descripteur de fichier associé. Cela signifie qu'après qu'un événement a été notifié par \fBepoll_wait\fP(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 \fBepoll\fP. L'utilisateur doit appeler \fBepoll_ctl\fP() avec \fBEPOLL_CTL_MOD\fP pour réarmer le descripteur de fichier avec le nouveau masque d'événement. .IP Cet drapeau est un drapeau d'entrée du champ \fIevent.events\fP lors d'un appel à \fBepoll_ctl\fP()\ ; il n'est jamais renvoyé par \fBepoll_wait\fP(2). .TP \fBEPOLLWAKEUP\fP (depuis Linux\ 3.5) .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 Si \fBEPOLLONESHOT\fP et \fBEPOLLET\fP sont vides et que le processus a la capacité \fBCAP_BLOCK_SUSPEND\fP, 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’\fBepoll_wait\fP(2) avant le prochain appel d’\fBepoll_wait\fP(2) sur le même descripteur de fichier \fBepoll\fP(7), la fermeture de ce descripteur de fichier, la suppression du descripteur de fichier de l'événement avec \fBEPOLL_CTL_DEL\fP, ou le vidage de \fBEPOLLWAKEUP\fP pour le descripteur de fichier de l'événement avec \fBEPOLL_CTL_MOD\fP. Consultez également \fBBOGUES\fP. .IP Cet drapeau est un drapeau d'entrée du champ \fIevent.events\fP lors d'un appel à \fBepoll_ctl\fP()\ ; il n'est jamais renvoyé par \fBepoll_wait\fP(2). .TP \fBEPOLLEXCLUSIVE\fP (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, \fIfd\fP. 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 \fBEPOLLEXCLUSIVE\fP, un ou plusieurs descripteurs de fichier epoll recevront un événement avec \fBepoll_wait\fP(2). Le comportement par défaut dans ce scénario (quand \fBEPOLLEXCLUSIVE\fP n'est pas défini) est que tous les descripteurs de fichier epoll reçoivent un événement. \fBEPOLLEXCLUSIVE\fP est ainsi utile pour éviter des problèmes de bousculade (thundering herd) dans certains scénarii. .IP Si un même descripteur de fichier est dans plusieurs instances epoll, certains ayant l'attribut \fBEPOLLEXCLUSIVE\fP et d'autres pas, les événements seront fournis à toutes les instances epoll qui n'ont pas indiqué \fBEPOLLEXCLUSIVE\fP et à au moins une des instances epoll où \fBEPOLLEXCLUSIVE\fP est indiqué. .IP Les valeurs suivantes peuvent être indiquées avec \fBEPOLLEXCLUSIVE\fP\ : \fBEPOLLIN\fP, \fBEPOLLOUT\fP, \fBEPOLLWAKEUP\fP et \fBEPOLLET\fP. \fBEPOLLHUP\fP et \fBEPOLLERR\fP 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 \fIevents\fP. Les tentatives d'indiquer d'autres valeurs dans \fIevents\fP provoquent l'erreur \fBEINVAL\fP. .IP \fBEPOLLEXCLUSIVE\fP ne peut être utilisé que dans une opération \fBEPOLL_CTL_ADD\fP\ ; les tentatives de l'utiliser avec \fBEPOLL_CTL_MOD\fP provoquent une erreur. Si \fBEPOLLEXCLUSIVE\fP a été positionné en utilisant \fBepoll_ctl\fP(), le \fBEPOLL_CTL_MOD\fP consécutif sur la même paire \fIepfd\fP,\ \fIfd\fP provoque une erreur. Un appel à \fBepoll_ctl\fP() qui indique \fBEPOLLEXCLUSIVE\fP dans \fIevents\fP et le descripteur de fichier cible \fIfd\fP en instance epoll échouera probablement. Dans tous ces cas, l'erreur est \fBEINVAL\fP. .IP Le drapeau \fBEPOLLEXCLUSIVE\fP est un drapeau d'entrée du champ \fIevent.events\fP lors d'un appel à \fBepoll_ctl\fP()\ ; il n'est jamais renvoyé par \fBepoll_wait\fP(2). .SH "VALEUR RENVOYÉE" Lorsqu'il réussit, l'appel \fBepoll_ctl\fP() renvoie zéro. Si une erreur se produit, \fBepoll_ctl\fP() renvoie \fB\-1\fP et \fIerrno\fP contient le code approprié. .SH ERREURS .TP \fBEBADF\fP \fIepfd\fP ou \fIfd\fP n'est pas un descripteur de fichier valable. .TP \fBEEXIST\fP \fIop\fP était \fBEPOLL_CTL_ADD\fP, mais le descripteur de fichier \fIfd\fP est déjà enregistré dans cette instance epoll. .TP \fBEINVAL\fP Le descripteur de fichier \fIepfd\fP, n'est pas un descripteur \fBepoll\fP, ou \fIfd\fP et \fIepfd\fP sont identiques, ou l'opération demandée \fIop\fP n'est pas gérée par cette interface. .TP \fBEINVAL\fP Un type d'événement non valable a été indiqué avec \fBEPOLLEXCLUSIVE\fP dans \fIevents\fP. .TP \fBEINVAL\fP \fIop\fP valait \fBEPOLL_CTL_MOD\fP et \fIevents\fP comprenait un \fBEPOLLEXCLUSIVE\fP. .TP \fBEINVAL\fP \fIop\fP valait \fBEPOLL_CTL_MOD\fP et le drapeau \fBEPOLLEXCLUSIVE\fP a été appliqué précédemment à la paire \fIepfd\fP,\ \fIfd\fP. .TP \fBEINVAL\fP \fBEPOLLEXCLUSIVE\fP était indiqué dans \fIevent\fP et \fIfd\fP se rapporte à une instance epoll. .TP \fBELOOP\fP \fIfd\fP se rapporte à une instance epoll et cette opération \fBEPOLL_CTL_ADD\fP créerait une boucle infinie d'instances epoll qui se surveilleraient mutuellement ou une profondeur d'arborescence d'instances epoll plus importante que 5. .TP \fBENOENT\fP \fIop\fP était \fBEPOLL_CTL_MOD\fP ou \fBEPOLL_CTL_DEL\fP, et \fIfd\fP n'était pas enregistré dans cette instance epoll. .TP \fBENOMEM\fP Pas assez de mémoire dans le noyau pour traiter l'opération \fIop\fP demandée. .TP \fBENOSPC\fP La limite imposée par \fI/proc/sys/fs/epoll/max_user_watches\fP a été rencontrée en essayant d'enregistrer (\fBEPOLL_CTL_ADD\fP), un nouveau descripteur de fichier, sur une instance epoll. Consultez \fBepoll\fP(7) pour plus de détails. .TP \fBEPERM\fP Le ficher cible \fIfd\fP ne prend pas en charge \fBepoll\fP. Cette erreur peut arriver si \fIfd\fP renvoie, par exemple, à un fichier ou à un répertoire régulier. .SH VERSIONS .\" To be precise: kernel 2.5.44. .\" The interface should be finalized by Linux kernel 2.5.66. \fBepoll_ctl\fP() 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. .SH CONFORMITÉ \fBepoll_ctl\fP() est spécifique à Linux. .SH NOTES L'interface \fBepoll\fP prend en charge tous les descripteurs de fichier gérés par \fBpoll\fP(2). .SH BOGUES Dans les versions du noyau antérieures à 2.6.9, l'opération \fBEPOLL_CTL_DEL\fP nécessitait un pointeur non NULL dans \fIevent\fP, alors que ce paramètre est ignoré. Depuis Linux 2.6.9, \fIevent\fP peut être NULL lors d'une opération \fBEPOLL_CTL_DEL\fP. Les applications qui doivent être portables pour les noyaux antérieurs à 2.6.9 devraient utiliser un pointeur différent de NULL dans \fIevent\fP. .PP .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change) .\" https://lwn.net/Articles/520198/ Si \fBEPOLLWAKEUP\fP est indiqué dans \fIflags\fP, mais que l’appelant n’a pas la capacité \fBCAP_BLOCK_SUSPEND\fP, alors l’attribut \fBEPOLLWAKEUP\fP est \fIignoré silencieusement\fP. Ce comportement malheureux est nécessaire parce qu’aucune vérification de validité n’était réalisée sur l’argument \fIflags\fP dans l’implémentation d’origine, et l’ajout du \fBEPOLLWAKEUP\fP avec une vérification forçant l’échec de l’appel si l’appelant n’avait pas la capacité \fBCAP_BLOCK_SUSPEND\fP 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é \fBCAP_BLOCK_SUSPEND\fP avant d’essayer d’utiliser l’attribut \fBEPOLLWAKEUP\fP. .SH "VOIR AUSSI" \fBepoll_create\fP(2), \fBepoll_wait\fP(2), \fBpoll\fP(2), \fBepoll\fP(7) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP 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/. .PP .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Jean-Philippe MENGUAL . .PP Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. .PP Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .