perkamon - en to fr translation catalogue (188 entries)

note: type: TH
en: 2012-04-17
fr: 17 avril 2012

note: type: TH
en: Linux Programmer's Manual
fr: Manuel du programmeur Linux

note: type: SH
en: NAME
fr: NOM

note: type: Plain text
en: epoll - I/O event notification facility
fr: epoll - Notifications d'événements d'entrées-sorties

note: type: Plain text
en: The B<epoll> API performs a similar task to B<poll>(2): monitoring multiple file descriptors to see if I/O is possible on any of them.  The B<epoll> API can be used either as an edge-triggered or a level-triggered interface and scales well to large numbers of watched file descriptors.  The following system calls are provided to create and manage an B<epoll> instance:
fr: L'interface de programmation (API) B<epoll> réalise une tâche similaire à B<poll>(2) : la surveillance de plusieurs descripteurs de fichier pour voir si les E/S y sont possibles. L'API B<epoll> peut être déclenchée par niveau ou par changement d'état, et s'adapte bien à un grand nombre de descripteurs simultanés. Les appels système suivants sont fournis pour créer et superviser une instance B<epoll> :

note: type: Plain text
en: B<epoll_create>(2)  creates an B<epoll> instance and returns a file descriptor referring to that instance.  (The more recent B<epoll_create1>(2)  extends the functionality of B<epoll_create>(2).)
fr: B<epoll_create>(2) créé une instance B<epoll> et renvoie un descripteur de fichier référençant cette instance (la dernière version d'B<epoll_create1>(2) étend les fonctionnalités d'B<epoll_create>(2)).

note: type: Plain text
en: Interest in particular file descriptors is then registered via B<epoll_ctl>(2).  The set of file descriptors currently registered on an B<epoll> instance is sometimes called an I<epoll> set.
fr: L'intérêt pour un descripteur de fichier est ensuite enregistré avec B<epoll_ctl>(2). L'ensemble des descripteurs de fichiers actuellement enregistrés pour une instance B<epoll> est parfois appelé un ensemble I<epoll>.

note: type: Plain text
en: B<epoll_wait>(2)  waits for I/O events, blocking the calling thread if no events are currently available.
fr: B<epoll_wait>(2) attend les événements d'E/S, en bloquant le thread appelant si aucun événement n'est actuellement disponible.

note: type: SS
en: Level-triggered and edge-triggered
fr: Détection de niveau et détection de transition

note: type: Plain text
en: The B<epoll> event distribution interface is able to behave both as edge-triggered (ET) and as level-triggered (LT).  The difference between the two mechanisms can be described as follows.  Suppose that this scenario happens:
fr: L'interface de distribution d'événements de B<epoll> est capable de se comporter en détection de niveau (Level Triggered - LT) ou en détection de transition (Edge Triggered - ET). La différence entre ces deux mécanismes est décrite ci-dessous. Supposons que le scénario suivant se produise\ :

note: type: Plain text
en: The file descriptor that represents the read side of a pipe (I<rfd>)  is registered on the B<epoll> instance.
fr: Le descripteur de fichier qui représente le côté lecture d'un tube (I<rfd>) est enregistré dans l'instance B<epoll>.

note: type: Plain text
en: A pipe writer writes 2 kB of data on the write side of the pipe.
fr: Celui qui écrit dans le tube envoie 2\ Ko de données.

note: type: Plain text
en: A call to B<epoll_wait>(2)  is done that will return I<rfd> as a ready file descriptor.
fr: Un appel à B<epoll_wait>(2) est effectué et renvoie I<rfd> comme descripteur de fichier prêt.

note: type: Plain text
en: The pipe reader reads 1 kB of data from I<rfd>.
fr: Le lecteur du tube lit 1\ Ko de données depuis I<rfd>.

note: type: Plain text
en: A call to B<epoll_wait>(2)  is done.
fr: Un appel de B<epoll_wait>(2) est effectué.

note: type: Plain text
en: If the I<rfd> file descriptor has been added to the B<epoll> interface using the B<EPOLLET> (edge-triggered)  flag, the call to B<epoll_wait>(2)  done in step B<5> will probably hang despite the available data still present in the file input buffer; meanwhile the remote peer might be expecting a response based on the data it already sent.  The reason for this is that edge-triggered mode delivers events only when changes occur on the monitored file descriptor.  So, in step B<5> the caller might end up waiting for some data that is already present inside the input buffer.  In the above example, an event on I<rfd> will be generated because of the write done in B<2> and the event is consumed in B<3>.  Since the read operation done in B<4> does not consume the whole buffer data, the call to B<epoll_wait>(2)  done in step B<5> might block indefinitely.
fr: Si le descripteur I<rfd> a été ajouté à l'ensemble B<epoll> en utilisant l'attribut B<EPOLLET> (edge-triggered), l'appel B<epoll_wait>(2), réalisé à l'étape B<5>, va probablement bloquer bien qu'il y ait des données toujours présentes dans les tampons d'entrée du fichier et le pair distant attendra une réponse basée sur les données qu'il a déjà envoyées. La raison en est que le mécanisme de distribution d'événements Edge Triggered délivre les événements seulement lorsque des événements surviennent sur le fichier supervisé. Ainsi, à l'étape B<5>, l'appelant peut attendre des données qui sont déjà présentes dans le tampon d'entrée. Dans l'exemple ci-dessus, un événement sur I<rfd> sera déclenché à cause de l'écriture à l'étape B<2>, et l'événement est consommé dans B<3>. Comme l'opération de lecture de l'étape B<4> ne consomme pas toutes les données du tampon, l'appel à B<epoll_wait>(2) effectué à l'étape B<5> peut verrouiller indéfiniment.

note: type: Plain text
en: An application that employs the B<EPOLLET> flag should use nonblocking file descriptors to avoid having a blocking read or write starve a task that is handling multiple file descriptors.  The suggested way to use B<epoll> as an edge-triggered (B<EPOLLET>)  interface is as follows:
fr: Une application qui emploie l'attribut B<EPOLLET> de la fonction B<epoll> devrait toujours utiliser des descripteurs non bloquants pour éviter qu'une lecture ou une écriture ne bloque, par une famine, une tâche qui gère plusieurs descripteurs de fichier. L'utilisation préconisée d'B<epoll> avec l'interface en détection de changements (B<EPOLLET>) est la suivante :

note: type: Plain text
en: with nonblocking file descriptors; and
fr: avec des descripteurs non bloquants\ ; et

note: type: Plain text
en: by waiting for an event only after B<read>(2)  or B<write>(2)  return B<EAGAIN>.
fr: en attendant seulement après qu'un B<read>(2) ou un B<write>(2) a renvoyé B<EAGAIN>.

note: type: Plain text
en: By contrast, when used as a level-triggered interface (the default, when B<EPOLLET> is not specified), B<epoll> is simply a faster B<poll>(2), and can be used wherever the latter is used since it shares the same semantics.
fr: Au contraire, lorsqu'il est utilisé avec l'interface en détection de niveau (par défaut si B<EPOLLET> n'est pas spécifié), B<epoll> est une alternative plus rapide à B<poll>(2), et peut être employé chaque fois que ce dernier est utilisé, car il utilise la même sémantique.

note: type: Plain text
en: Since even with edge-triggered B<epoll>, multiple events can be generated upon receipt of multiple chunks of data, the caller has the option to specify the B<EPOLLONESHOT> flag, to tell B<epoll> to disable the associated file descriptor after the receipt of an event with B<epoll_wait>(2).  When the B<EPOLLONESHOT> flag is specified, it is the caller's responsibility to rearm the file descriptor using B<epoll_ctl>(2)  with B<EPOLL_CTL_MOD>.
fr: Même dans un B<epoll> de type Edge Triggered, plusieurs événements peuvent être générés à la réception de nombreux blocs de données. L'appelant peut, en spécifiant l'attribut B<EPOLLONESHOT>, faire désactiver par B<epoll> le descripteur de fichier associé, après la réception d'un événement avec B<epoll_wait>(2). Lorsque l'attribut B<EPOLLONESHOT> est spécifié, il est de la responsabilité de l'appelant de réarmer le descripteur en utilisant B<epoll_ctl>(2) avec B<EPOLL_CTL_MOD>.

note: type: SS
en: /proc interfaces
fr: Interfaces /proc

note: Following was added in 2.6.28, but them removed in 2.6.29 .TP .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)" This specifies an upper limit on the number of epoll instances that can be created per real user ID. type: Plain text
en: The following interfaces can be used to limit the amount of kernel memory consumed by epoll:
fr: Les interfaces suivantes peuvent être utilisées pour limiter la quantité de mémoire du noyau utilisée par epoll\ :

note: type: TP
en: I</proc/sys/fs/epoll/max_user_watches> (since Linux 2.6.28)
fr: I</proc/sys/fs/epoll/max_user_watches> (depuis Linux 2.6.28)

note: 2.6.29 (in 2.6.28, the default was 1/32 of lowmem) type: Plain text
en: This specifies a limit on the total number of file descriptors that a user can register across all epoll instances on the system.  The limit is per real user ID.  Each registered file descriptor costs roughly 90 bytes on a 32-bit kernel, and roughly 160 bytes on a 64-bit kernel.  Currently, the default value for I<max_user_watches> is 1/25 (4%) of the available low memory, divided by the registration cost in bytes.
fr: Cela définit une limite au nombre total de descripteurs de fichiers qu'un utilisateur peut enregistrer au travers de toutes les instances epoll du système. La limite est imposée par identifiant d'utilisateur réel. Chaque descripteur de fichier enregistré coûte environ 90 octets sur un noyau 32 bits et environ 160 octets sur un noyau 64 bits. Actuellement la valeur par défaut pour I<max_user_watches> est de 1/25 (4%) de la mémoire basse disponible, divisé par le coût d'allocation en octets.

note: type: SS
en: Example for suggested usage
fr: Exemple d'utilisation

note: type: Plain text
en: While the usage of B<epoll> when employed as a level-triggered interface does have the same semantics as B<poll>(2), the edge-triggered usage requires more clarification to avoid stalls in the application event loop.  In this example, listener is a nonblocking socket on which B<listen>(2)  has been called.  The function I<do_use_fd()> uses the new ready file descriptor until B<EAGAIN> is returned by either B<read>(2)  or B<write>(2).  An event-driven state machine application should, after having received B<EAGAIN>, record its current state so that at the next call to I<do_use_fd()> it will continue to B<read>(2)  or B<write>(2)  from where it stopped before.
fr: Tandis que l'utilisation de B<epoll> avec un déclenchement par niveau correspond à la même sémantique que B<poll>(2), le déclenchement par changement d'état nécessite plus d'explication pour éviter les cas de blocage. Dans cet exemple, le lecteur emploie une socket non bloquante sur laquelle B<listen>(2) a été appelée. La fonction I<do_use_fd()> va utiliser le nouveau descripteur de fichier, jusqu'à ce que B<EAGAIN> soit renvoyé par B<read>(2) ou par B<write>(2). Une application fonctionnant par transition d'état devrait, après réception d'B<EAGAIN>, enregistrer l'état en cours, afin que l'appel suivant de I<do_use_fd()> continue avec le B<read>(2) ou le B<write>(2) où il s'est arrêté.

note: type: Plain text
en: When used as an edge-triggered interface, for performance reasons, it is possible to add the file descriptor inside the B<epoll> interface (B<EPOLL_CTL_ADD>)  once by specifying (B<EPOLLIN>|B<EPOLLOUT>).  This allows you to avoid continuously switching between B<EPOLLIN> and B<EPOLLOUT> calling B<epoll_ctl>(2)  with B<EPOLL_CTL_MOD>.
fr: Lorsqu'on utilise une détection de changement d'états, pour des raisons de performances, il est possible d'ajouter le descripteur de fichier dans l'interface B<epoll> (B<EPOLL_CTL_ADD>) une fois, en spécifiant (B<EPOLLIN>|B<EPOLLOUT>). Cela évite de basculer sans cesse entre B<EPOLLIN> et B<EPOLLOUT> lors des appels B<epoll_ctl>(2) avec B<EPOLL_CTL_MOD>.

note: type: SS
en: Questions and answers
fr: Questions/Réponses

note: type: Plain text
en: What is the key used to distinguish the file descriptors registered in an B<epoll> set?
fr: Quelle est la clé utilisée pour distinguer les descripteurs de fichier enregistrés dans un ensemble B<epoll> ?

note: type: Plain text
en: The key is the combination of the file descriptor number and the open file description (also known as an "open file handle", the kernel's internal representation of an open file).
fr: La clé est une combinaison du numéro du descripteur de fichier et de la description du fichier ouvert (aussi connue comme « open file handle », la représentation interne au noyau d'un fichier ouvert).

note: type: Plain text
en: What happens if you register the same file descriptor on an B<epoll> instance twice?
fr: Que se passe-t-il si on enregistre deux fois le même descripteur de fichier dans une instance B<epoll>\ ?

note: But a descriptor duplicated by fork(2) can't be added to the set, because the [file *, fd] pair is already in the epoll set. That is a somewhat ugly inconsistency.  On the one hand, a child process cannot add the duplicate file descriptor to the epoll set.  (In every other case that I can think of, 
en: You will probably get B<EEXIST>.  However, it is possible to add a duplicate (B<dup>(2), B<dup2>(2), B<fcntl>(2)  B<F_DUPFD>)  descriptor to the same B<epoll> instance.  This can be a useful technique for filtering events, if the duplicate file descriptors are registered with different I<events> masks.
fr: Vous aurez probablement un B<EEXIST>. Cependant il est possible d'ajouter un duplicat de descripteur (B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD>) sur la même instance B<epoll>. Cela peut être une technique utile pour le filtrage d'événements, si les descripteurs duplicats sont enregistrés avec un masque d'événements I<events> différent.

note: type: Plain text
en: Can two B<epoll> instances wait for the same file descriptor? If so, are events reported to both B<epoll> file descriptors?
fr: Deux instances B<epoll> peuvent-elles attendre le même descripteur de fichier\ ? Si oui, les événements seront-ils reportés sur les deux descripteurs de fichier B<epoll> en même temps\ ?

note: type: Plain text
en: Yes, and events would be reported to both.  However, careful programming may be needed to do this correctly.
fr: Oui, et les événements seront rapportés aux deux. Toutefois, une programmation soignée est nécessaire pour que cela soit fait correctement.

note: type: Plain text
en: Is the B<epoll> file descriptor itself poll/epoll/selectable?
fr: Peut-on utiliser le descripteur de B<epoll> lui-même avec poll/epoll/select\ ?

note: type: Plain text
en: Yes.  If an B<epoll> file descriptor has events waiting, then it will indicate as being readable.
fr: Oui. Si un descripteur de fichier B<epoll> a des événements en attente, alors il indiquera qu'il est lisible.

note: type: Plain text
en: What happens if one attempts to put an B<epoll> file descriptor into its own file descriptor set?
fr: Que se passe-t-il si on cherche à placer un descripteur de B<epoll> dans son propre ensemble\ ?

note: type: Plain text
en: The B<epoll_ctl>(2)  call will fail (B<EINVAL>).  However, you can add an B<epoll> file descriptor inside another B<epoll> file descriptor set.
fr: L'appel à B<epoll_ctl>(2) échouera (B<EINVAL>). Toutefois vous pouvez ajouter un descripteur de B<epoll> dans un autre ensemble B<epoll>.

note: type: Plain text
en: Can I send an B<epoll> file descriptor over a UNIX domain socket to another process?
fr: Puis-je envoyer le descripteur de B<epoll> à travers une socket UNIX vers un autre processus\ ?

note: type: Plain text
en: Yes, but it does not make sense to do this, since the receiving process would not have copies of the file descriptors in the B<epoll> set.
fr: Oui, mais il n'y a aucune raison de faire ça, puisque le processus récepteur n'aura pas de copie des descripteurs de fichier de l'ensemble B<epoll>.

note: type: Plain text
en: Will closing a file descriptor cause it to be removed from all B<epoll> sets automatically?
fr: Est-ce que la fermeture d'un descripteur le supprime automatiquement de tous les ensembles B<epoll>\ ?

note: type: Plain text
en: Yes, but be aware of the following point.  A file descriptor is a reference to an open file description (see B<open>(2)).  Whenever a descriptor is duplicated via B<dup>(2), B<dup2>(2), B<fcntl>(2)  B<F_DUPFD>, or B<fork>(2), a new file descriptor referring to the same open file description is created.  An open file description continues to exist until all file descriptors referring to it have been closed.  A file descriptor is removed from an B<epoll> set only after all the file descriptors referring to the underlying open file description have been closed (or before if the descriptor is explicitly removed using B<epoll_ctl>(2)  B<EPOLL_CTL_DEL>).  This means that even after a file descriptor that is part of an B<epoll> set has been closed, events may be reported for that file descriptor if other file descriptors referring to the same underlying file description remain open.
fr: Oui, mais prenez note des points suivants. Un descripteur de fichier est une référence vers la description d'un fichier ouvert (consultez B<open>(2)). À chaque fois qu'un descripteur est dupliqué avec B<dup>(2), B<dup2>(2), B<fcntl>(2) B<F_DUPFD> ou B<fork>(2), un nouveau descripteur de fichier qui se réfère au même fichier ouvert est créé. Une description de fichier ouvert continue d'exister jusqu'à ce que tous les descripteurs de fichier qui s'y réfèrent soient fermés. Un descripteur de fichier n'est retiré d'un ensemble B<epoll> qu'après la fermeture de tous les descripteurs de fichier qui se réfèrent à la description de fichier ouvert sous-jacente (ou avant si le descripteur est explicitement retiré en utilisant B<epoll_ctl>(2) B<EPOLL_CTL_DEL>). Cela signifie que même après la fermeture d'un descripteur de fichier d'un ensemble B<epoll>, des événements peuvent toujours être remontés pour ce descripteur de fichier si d'autres descripteurs de fichier, se référant à la même description de fichier sous-jacente, restent ouverts.

note: type: Plain text
en: If more than one event occurs between B<epoll_wait>(2)  calls, are they combined or reported separately?
fr: Si plus d'un événement surviennent entre deux appels B<epoll_wait>(2), sont-ils combinés ou rapportés séparément\ ?

note: type: Plain text
en: They will be combined.
fr: Ils sont combinés.

note: type: Plain text
en: Does an operation on a file descriptor affect the already collected but not yet reported events?
fr: Est-ce qu'une opération sur un descripteur affecte les événements déjà collectés mais pas encore rapportés\ ?

note: type: Plain text
en: You can do two operations on an existing file descriptor.  Remove would be meaningless for this case.  Modify will reread available I/O.
fr: Vous pouvez faire deux choses sur un descripteur existant. Une suppression serait sans signification dans ce cas. Une modification revérifie les entrées-sorties disponibles.

note: type: Plain text
en: Do I need to continuously read/write a file descriptor until B<EAGAIN> when using the B<EPOLLET> flag (edge-triggered behavior) ?
fr: Dois-je lire/écrire sans cesse un descripteur jusqu'à obtenir B<EAGAIN> avec l'attribut B<EPOLLET> (comportement edge-triggered)\ ?

note: type: Plain text
en: Receiving an event from B<epoll_wait>(2)  should suggest to you that such file descriptor is ready for the requested I/O operation.  You must consider it ready until the next (nonblocking)  read/write yields B<EAGAIN>.  When and how you will use the file descriptor is entirely up to you.
fr: La réception d'un événement depuis B<epoll_wait>(2) suggère qu'un descripteur est prêt pour l'opération d'E/S désirée. Vous devez le considérer prêt jusqu'à ce que la prochaine lecture ou écriture (non bloquante) remonte un B<EAGAIN>. Quand et comment utiliser le descripteur dépend de vous.

note: type: Plain text
en: For packet/token-oriented files (e.g., datagram socket, terminal in canonical mode), the only way to detect the end of the read/write I/O space is to continue to read/write until B<EAGAIN>.
fr: Pour les fichiers orientés paquet ou jeton (par exemple, une socket datagramme ou un terminal en mode canonique), la seule façon de détecter la fin de l'espace d'entrée-sortie pour les lectures ou écritures est de continuer à lire ou écrire jusqu'à la réception d'un B<EAGAIN>.

note: type: Plain text
en: For stream-oriented files (e.g., pipe, FIFO, stream socket), the condition that the read/write I/O space is exhausted can also be detected by checking the amount of data read from / written to the target file descriptor.  For example, if you call B<read>(2)  by asking to read a certain amount of data and B<read>(2)  returns a lower number of bytes, you can be sure of having exhausted the read I/O space for the file descriptor.  The same is true when writing using B<write>(2).  (Avoid this latter technique if you cannot guarantee that the monitored file descriptor always refers to a stream-oriented file.)
fr: Pour les fichiers orientés flux (par exemple, les tubes, FIFO ou sockets en mode flux), la disponibilité des entrées-sorties peut-être vérifiée par la quantité de données lues ou écrites avec le descripteur. Par exemple, si vous appelez B<read>(2) en demandant la lecture d'une certaine quantité de données et que B<read>(2) en renvoie moins, vous pouvez être sûrs d'avoir consommé tout le tampon d'entrée pour le descripteur. La même chose est vraie pour l'appel système B<write>(2). (Évitez cette dernière technique si vous ne pouvez garantir que le descripteur de fichier surveillé correspond toujours à un fichier de type flux)

note: type: SS
en: Possible pitfalls and ways to avoid them
fr: Erreurs possibles et moyens de les éviter

note: type: TP
en: B<o Starvation (edge-triggered)>
fr: B<o Famine (edge-triggered)>

note: type: Plain text
en: If there is a large amount of I/O space, it is possible that by trying to drain it the other files will not get processed causing starvation.  (This problem is not specific to B<epoll>.)
fr: S'il y a un gros volume d'entrées-sorties, il est possible qu'en essayant de les traiter, d'autres fichiers ne soient pas pris en compte, ce qu'on appelle un cas de famine. Ce problème n'est pas spécifique à B<epoll>.

note: type: Plain text
en: The solution is to maintain a ready list and mark the file descriptor as ready in its associated data structure, thereby allowing the application to remember which files need to be processed but still round robin amongst all the ready files.  This also supports ignoring subsequent events you receive for file descriptors that are already ready.
fr: La solution est de maintenir une liste de descripteurs prêts et de les marquer comme tels dans leur structure associée, permettant à l'application de savoir quels fichiers traiter, en organisant l'ordre au mieux. Cela permet aussi d'ignorer les événements ultérieurs sur des descripteurs prêts.

note: type: TP
en: B<o If using an event cache...>
fr: B<o Utilisation d'un cache d'événements...>

note: type: Plain text
en: If you use an event cache or store all the file descriptors returned from B<epoll_wait>(2), then make sure to provide a way to mark its closure dynamically (i.e., caused by a previous event's processing).  Suppose you receive 100 events from B<epoll_wait>(2), and in event #47 a condition causes event #13 to be closed.  If you remove the structure and B<close>(2)  the file descriptor for event #13, then your event cache might still say there are events waiting for that file descriptor causing confusion.
fr: Si vous utilisez un cache d'événement, ou stockez tous les descripteurs renvoyés par B<epoll_wait>(2), alors assurez-vous de disposer d'un moyen de marquer dynamiquement leurs fermetures (causées par un événement précédent). Supposons que vous recevez 100 événements de B<epoll_wait>(2), et que l'événement 47 implique de fermer le descripteur 13. Si vous supprimez la structure et utilisez B<close>(2), alors votre cache peut encore contenir des événements pour ce descripteur, et poser des problèmes de cohérence.

note: type: Plain text
en: One solution for this is to call, during the processing of event 47, B<epoll_ctl>(B<EPOLL_CTL_DEL>)  to delete file descriptor 13 and B<close>(2), then mark its associated data structure as removed and link it to a cleanup list.  If you find another event for file descriptor 13 in your batch processing, you will discover the file descriptor had been previously removed and there will be no confusion.
fr: Une solution est d'invoquer, pendant le traitement de l'événement 47, B<epoll_ctl>(B<EPOLL_CTL_DEL>) pour supprimer le descripteur 13, le fermer avec B<close>(2), et marquer sa structure associée comme supprimée. Si vous rencontrez un autre événement pour le descripteur 13 dans votre traitement, vous verrez qu'il a été supprimé précédemment, sans que cela ne prête à confusion.

note: Its interface should be finalized in Linux kernel 2.5.66. type: Plain text
en: The B<epoll> API was introduced in Linux kernel 2.5.44.  Support was added to glibc in version 2.3.2.
fr: L'API B<epoll> a été introduite dans le noyau Linux 2.5.44. La prise en charge par la glibc a été ajoutée dans la version 2.3.2.

note: type: SH
en: CONFORMING TO
fr: CONFORMITÉ

note: type: Plain text
en: The B<epoll> API is Linux-specific.  Some other systems provide similar mechanisms, for example, FreeBSD has I<kqueue>, and Solaris has I</dev/poll>.
fr: L'API B<epoll> est spécifique à Linux. Certains autres systèmes fournissent des mécanismes similaires. Par exemple, FreeBSD propose I<kqueue> et Solaris I</dev/poll>.

note: type: SH
en: SEE ALSO
fr: VOIR AUSSI

note: type: Plain text
en: This page is part of release 3.65 of the Linux I<man-pages> project.  A description of the project, and information about reporting bugs, can be found at \%http://www.kernel.org/doc/man-pages/.
fr: Cette page fait partie de la publication 3.65 du projet I<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/.

note: type: TH
en: 2012-04-15
fr: 15 avril 2012

note: type: Plain text
en: epoll_create, epoll_create1 - open an epoll file descriptor
fr: epoll_create, epoll_create1 - Ouvrir un descripteur de fichier epoll

note: type: Plain text
en: B<epoll_create>()  creates an B<epoll>(7)  instance.  Since Linux 2.6.8, the I<size> argument is ignored, but must be greater than zero; see NOTES below.
fr: B<epoll_create>() crée une instance B<epoll>(7). Depuis Linux 2.6.8, le paramètre I<size> est ignoré, mais doit être strictement positif. Consultez B<NOTES> ci-dessous.

note: type: Plain text
en: B<epoll_create>()  returns a file descriptor referring to the new epoll instance.  This file descriptor is used for all the subsequent calls to the B<epoll> interface.  When no longer required, the file descriptor returned by B<epoll_create>()  should be closed by using B<close>(2).  When all file descriptors referring to an epoll instance have been closed, the kernel destroys the instance and releases the associated resources for reuse.
fr: B<epoll_create>() renvoie un descripteur de fichier référençant la nouvelle instance epoll. Ce descripteur de fichier est utilisé pour tous les appels à l'interface B<epoll>. Lorsqu'il n'est plus nécessaire, le descripteur de fichier renvoyé par B<epoll_create>() devrait être fermé avec B<close>(2). Lorsque tous les descripteurs de fichier faisant référence à une instance epoll sont fermés, le noyau détruit l'instance et libère les ressources associées pour une nouvelle utilisation.

note: type: Plain text
en: If I<flags> is 0, then, other than the fact that the obsolete I<size> argument is dropped, B<epoll_create1>()  is the same as B<epoll_create>().  The following value can be included in I<flags> to obtain different behavior:
fr: Si I<flags> vaut 0, alors, en plus du fait que le paramètre obsolète I<size> n'est plus précisé, B<epoll_create1>() est identique à B<epoll_create>(). La valeur suivante peut être incluse dans I<flags> pour obtenir un comportement différent :

note: type: Plain text
en: Set the close-on-exec (B<FD_CLOEXEC>)  flag on the new file descriptor.  See the description of the B<O_CLOEXEC> flag in B<open>(2)  for reasons why this may be useful.
fr: Placer l'attribut « close-on-exec » (B<FD_CLOEXEC>) sur le nouveau descripteur de fichier. Consultez la description de l'attribut B<O_CLOEXEC> dans B<open>(2) pour savoir pourquoi cela peut être utile.

note: type: SH
en: RETURN VALUE
fr: VALEUR RENVOYÉE

note: type: Plain text
en: On success, these system calls return a nonnegative file descriptor.  On error, -1 is returned, and I<errno> is set to indicate the error.
fr: S'il réussit, ces appels système renvoient un descripteur de fichier positif. En cas d'erreur, ils renvoient -1 et remplissent I<errno> avec la valeur d'erreur.

note: type: SH
en: ERRORS
fr: ERREURS

note: type: Plain text
en: I<size> is not positive.
fr: I<size> est négatif ou nul.

note: type: Plain text
en: (B<epoll_create1>())  Invalid value specified in I<flags>.
fr: (B<epoll_create1>()) I<flags> contient une valeur incorrecte.

note: type: Plain text
en: The per-user limit on the number of epoll instances imposed by I</proc/sys/fs/epoll/max_user_instances> was encountered.  See B<epoll>(7)  for further details.
fr: La limite par utilisateur du nombre d'instances epoll imposée par I</proc/sys/fs/epoll/max_user_instances> a été atteinte. Consultez B<epoll>(7) pour plus de détails.

note: type: Plain text
en: The system limit on the total number of open files has been reached.
fr: La limite du nombre total de fichiers ouverts sur le système a été atteinte.

note: type: Plain text
en: There was insufficient memory to create the kernel object.
fr: Il n'y a pas assez de mémoire pour que le noyau crée les objets nécessaires.

note: type: Plain text
en: B<epoll_create>()  was added to the kernel in version 2.6.  Library support is provided in glibc starting with version 2.3.2.
fr: B<epoll_create> a été introduite dans le noyau Linux 2.6. La prise en charge par la glibc a été ajoutée dans la version 2.3.2.

note: To be precise: kernel 2.5.44. The interface should be finalized by Linux kernel 2.5.66. type: Plain text
en: B<epoll_create1>()  was added to the kernel in version 2.6.27.  Library support is provided in glibc starting with version 2.9.
fr: B<epoll_create1> a été introduite dans le noyau Linux 2.6.27. La prise en charge par la glibc a été ajoutée dans la version 2.9.

note: type: Plain text
en: B<epoll_create>()  is Linux-specific.
fr: B<epoll_create>() est spécifique à Linux.

note: type: Plain text
en: In the initial B<epoll_create>()  implementation, the I<size> argument informed the kernel of the number of file descriptors that the caller expected to add to the B<epoll> instance.  The kernel used this information as a hint for the amount of space to initially allocate in internal data structures describing events.  (If necessary, the kernel would allocate more space if the caller's usage exceeded the hint given in I<size>.)  Nowadays, this hint is no longer required (the kernel dynamically sizes the required data structures without needing the hint), but I<size> must still be greater than zero, in order to ensure backward compatibility when new B<epoll> applications are run on older kernels.
fr: Dans l'implémentation initiale d'B<epoll_create>(), le paramètre I<size> informait le noyau du nombre de descripteurs de fichier que l'appelant s'attend à ajouter à l'instance B<epoll>. Le noyau utilisait ce renseignement comme indice pour la quantité d'espace à allouer initialement dans les structures de données internes décrivant les événements (si nécessaire, le noyau allouerait plus d'espace si l'utilisation de l'appelant dépasse l'indice donné en I<size>). Maintenant, cet indice n'est plus nécessaire (le noyau dimensionne dynamiquement les structures de données sans avoir besoin de cet indice), mais I<size> doit toujours être strictement positif, par compatibilité ascendante, si de nouvelles applications B<epoll> sont exécutées sur d'anciens noyaux.

note: type: Plain text
en: epoll_ctl - control interface for an epoll descriptor
fr: epoll_ctl - Interface de contrôle pour un descripteur epoll

note: type: Plain text
en: This system call performs control operations on the B<epoll>(7)  instance referred to by the file descriptor I<epfd>.  It requests that the operation I<op> be performed for the target file descriptor, I<fd>.
fr: Cet appel système effectue des opérations de contrôle sur l'instance B<epoll>(7) référencée par le descripteur de fichier I<epfd>. Il nécessite que l'opération I<op> soit effectuée sur le descripteur de fichier cible I<fd>.

note: type: Plain text
en: Valid values for the I<op> argument are :
fr: Les valeurs autorisées pour le paramètre I<op> sont\ :

note: type: Plain text
en: Register the target file descriptor I<fd> on the B<epoll> instance referred to by the file descriptor I<epfd> and associate the event I<event> with the internal file linked to I<fd>.
fr: Enregistre le descripteur de fichier cible I<fd> pour l'instance B<epoll> indiquée par le descripteur de fichier I<epfd> et associe l'événement I<event> avec le fichier représenté par I<fd>.

note: type: Plain text
en: Change the event I<event> associated with the target file descriptor I<fd>.
fr: Change l'événement I<event> associé au descripteur de fichier I<fd>.

note: type: Plain text
en: Remove (deregister) the target file descriptor I<fd> from the B<epoll> instance referred to by I<epfd>.  The I<event> is ignored and can be NULL (but see BUGS below).
fr: Supprime (désenregistre) le descripteur de fichier I<fd> de l'instance B<epoll> indiquée par I<epfd>. Le paramètre I<event> est ignoré et peut être NULL (mais consultez la section BOGUES ci\(hydessous).

note: type: Plain text
en: The I<event> argument describes the object linked to the file descriptor I<fd>.  The I<struct epoll_event> is defined as :
fr: Le paramètre I<event> décrit l'objet lié au descripteur de fichier I<fd>. La structure I<epoll_event> est définie ainsi\ :

note: type: Plain text
en: struct epoll_event {
        uint32_t     events;      /* Epoll events */
        epoll_data_t data;        /* User data variable */
    };
fr: struct epoll_event {
        uint32_t events;        /* Événements epoll     */
        epoll_data_t data;      /* Variable utilisateur */
    };

note: type: Plain text
en: The I<events> member is a bit set composed using the following available event types:
fr: Le membre I<events> est un masque de bits composé à partir des événements disponibles suivants\ :

note: type: Plain text
en: The associated file is available for B<read>(2)  operations.
fr: Le descripteur associé est disponible pour un appel B<read>(2).

note: type: Plain text
en: The associated file is available for B<write>(2)  operations.
fr: Le descripteur associé est disponible pour un appel B<write>(2).

note: type: TP
en: B<EPOLLRDHUP> (since Linux 2.6.17)
fr: B<EPOLLRDHUP> (depuis Linux 2.6.17)

note: type: Plain text
en: Stream socket peer closed connection, or shut down writing half of connection.  (This flag is especially useful for writing simple code to detect peer shutdown when using Edge Triggered monitoring.)
fr: 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.)

note: type: Plain text
en: There is urgent data available for B<read>(2)  operations.
fr: Il y a des données urgentes disponibles pour un appel B<read>(2).

note: type: Plain text
en: Error condition happened on the associated file descriptor.  B<epoll_wait>(2)  will always wait for this event; it is not necessary to set it in I<events>.
fr: Une erreur s'est produite sur le descripteur de fichier associé. B<epoll_wait>(2) attend toujours cet événement, il n'est pas nécessaire de l'indiquer dans I<events>.

note: type: Plain text
en: Hang up happened on the associated file descriptor.  B<epoll_wait>(2)  will always wait for this event; it is not necessary to set it in I<events>.
fr: Une déconnexion s'est produite sur le descripteur associé. B<epoll_wait>(2) attend toujours cet événement, il n'est pas nécessaire de l'indiquer dans I<events>.

note: type: Plain text
en: Sets the Edge Triggered behavior for the associated file descriptor.  The default behavior for B<epoll> is Level Triggered.  See B<epoll>(7)  for more detailed information about Edge and Level Triggered event distribution architectures.
fr: Définir le comportement en détection de changement d'état sur le descripteur. Par défaut B<epoll> fonctionne en détection de niveau. Consultez B<epoll>(7) pour plus de détails sur les comportements en détection de niveau et de changements d'état.

note: type: TP
en: B<EPOLLONESHOT> (since Linux 2.6.2)
fr: B<EPOLLONESHOT> (depuis Linux 2.6.2)

note: type: Plain text
en: Sets the one-shot behavior for the associated file descriptor.  This means that after an event is pulled out with B<epoll_wait>(2)  the associated file descriptor is internally disabled and no other events will be reported by the B<epoll> interface.  The user must call B<epoll_ctl>()  with B<EPOLL_CTL_MOD> to rearm the file descriptor with a new event mask.
fr: Définir le comportement «\ coup unique\ » (Ndt\ : one\(hyshot) pour le descripteur de fichier associé. Cela signifie qu'après qu'un événement a été retiré avec B<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 B<epoll>. L'utilisateur doit appeler B<epoll_ctl>() avec B<EPOLL_CTL_MOD> pour réarmer le descripteur de fichier avec le nouveau masque d'événement.

note: type: Plain text
en: When successful, B<epoll_ctl>()  returns zero.  When an error occurs, B<epoll_ctl>()  returns -1 and I<errno> is set appropriately.
fr: Lorsqu'il réussit, l'appel B<epoll_ctl>() renvoie zéro. Si une erreur se produit, B<epoll_ctl>() renvoie -1 et I<errno> contient le code approprié.

note: type: Plain text
en: I<epfd> or I<fd> is not a valid file descriptor.
fr: I<epfd> ou I<fd> n'est pas un descripteur de fichier valable.

note: type: Plain text
en: I<op> was B<EPOLL_CTL_ADD>, and the supplied file descriptor I<fd> is already registered with this epoll instance.
fr: I<op> est B<EPOLL_CTL_ADD>, mais le descripteur de fichier I<fd> est déjà enregistrée dans cette instance epoll.

note: type: Plain text
en: I<epfd> is not an B<epoll> file descriptor, or I<fd> is the same as I<epfd>, or the requested operation I<op> is not supported by this interface.
fr: Le descripteur de fichier I<epfd>, n'est pas un descripteur B<epoll>, ou I<fd> et I<epfd> sont identiques, ou l'opération demandée I<op> n'est pas supportée par cette interface.

note: type: Plain text
en: I<op> was B<EPOLL_CTL_MOD> or B<EPOLL_CTL_DEL>, and I<fd> is not registered with this epoll instance.
fr: I<op> est B<EPOLL_CTL_MOD> ou B<EPOLL_CTL_DEL>, et I<fd> n'est pas enregistré dans cette instance epoll.

note: type: Plain text
en: There was insufficient memory to handle the requested I<op> control operation.
fr: Pas assez de mémoire dans le noyau pour traiter l'opération I<op> demandée.

note: type: Plain text
en: The limit imposed by I</proc/sys/fs/epoll/max_user_watches> was encountered while trying to register (B<EPOLL_CTL_ADD>)  a new file descriptor on an epoll instance.  See B<epoll>(7)  for further details.
fr: La limite imposée par I</proc/sys/fs/epoll/max_user_watches> a été rencontrée en essayant d'enregistrer (B<EPOLL_CTL_ADD>) un nouveau descripteur de fichier sur une instance epoll. Consultez B<epoll>(7) pour plus de détails.

note: type: Plain text
en: The target file I<fd> does not support B<epoll>.
fr: Le fichier cible I<fd> n'est pas supporté par B<epoll>.

note: To be precise: kernel 2.5.44. The interface should be finalized by Linux kernel 2.5.66. type: Plain text
en: B<epoll_ctl>()  was added to the kernel in version 2.6.
fr: B<epoll_ctl>() a été ajouté au noyau Linux dans sa version 2.6.

note: type: Plain text
en: B<epoll_ctl>()  is Linux-specific.  Library support is provided in glibc starting with version 2.3.2.
fr: B<epoll_ctl>() est spécifique à Linux. La prise en charge par la glibc a été ajoutée dans la version 2.3.2.

note: type: Plain text
en: The B<epoll> interface supports all file descriptors that support B<poll>(2).
fr: L'interface B<epoll> supporte tous les descripteurs de fichier supportés par B<poll>(2).

note: type: SH
en: BUGS
fr: BOGUES

note: type: Plain text
en: In kernel versions before 2.6.9, the B<EPOLL_CTL_DEL> operation required a non-null pointer in I<event>, even though this argument is ignored.  Since Linux 2.6.9, I<event> can be specified as NULL when using B<EPOLL_CTL_DEL>.  Applications that need to be portable to kernels before 2.6.9 should specify a non-null pointer in I<event>.
fr: Dans les versions du noyau antérieures à 2.6.9, l'opération B<EPOLL_CTL_DEL> nécessitait un pointeur non NULL dans I<event>, alors que ce paramètre est ignoré. Depuis Linux 2.6.9, I<event> peut être NULL lors d'une opération B<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 I<event>.

note: type: TH
en: 2014-01-31
fr: 31 janvier 2014

note: type: Plain text
en: epoll_wait, epoll_pwait - wait for an I/O event on an epoll file descriptor
fr: epoll_wait, epoll_pwait - Attendre un événement sur un descripteur epoll

note: type: Plain text
en: The B<epoll_wait>()  system call waits for events on the B<epoll>(7)  instance referred to by the file descriptor I<epfd>.  The memory area pointed to by I<events> will contain the events that will be available for the caller.  Up to I<maxevents> are returned by B<epoll_wait>().  The I<maxevents> argument must be greater than zero.
fr: L'appel système B<epoll_wait>() attend un événement sur l'instance B<epoll>(7) indiquée par le descripteur I<epfd>. La zone mémoire pointée par I<events> contiendra les événements disponibles pour l'appelant. Un maximum de I<maxevents> événements sont renvoyés par B<epoll_wait>(). Le paramètre I<maxevents> doit être supérieur à zéro.

note: type: Plain text
en: The I<timeout> argument specifies the number of milliseconds that B<epoll_wait>()  will block.  The call will block until either:
fr: L'argument I<timeout> définit le temps en milliseconde pendant lequel B<epoll_wait>() bloquera. L’appel bloquera jusqu’au premier événement suivant :

note: type: Plain text
en: a file descriptor delivers an event;
fr: un descripteur de fichier délivre un événement ;

note: type: Plain text
en: the call is interrupted by a signal handler; or
fr: l’appel est interrompu par un gestionnaire de signal ;

note: type: Plain text
en: the timout expires.
fr: le délai expire.

note: type: Plain text
en: Note that the I<timeout> interval will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.  Specifying a I<timeout> of -1 causes B<epoll_wait>()  to block indefinitely, while specifying a I<timeout> equal to zero cause B<epoll_wait>()  to return immediately, even if no events are available.
fr: Remarquez que l’intervalle I<timeout> sera arrondi à la granularité de l'horloge système et que les délais d'ordonnancement du noyau signifient que l'intervalle de blocage pourrait être dépassé d'une petite quantité. Un I<timeout> de -1 force B<epoll_wait>() à attendre indéfiniment, alors qu'un I<timeout> nul force B<epoll_wait>() à se terminer immédiatement, même si aucun événement n'est disponible.

note: type: Plain text
en: The I<struct epoll_event> is defined as :
fr: La structure I<epoll_event> est définie ainsi\ :

note: type: Plain text
en: struct epoll_event {
        uint32_t     events;    /* Epoll events */
        epoll_data_t data;      /* User data variable */
    };
fr: struct epoll_event {
        uint32_t     events;    /* Événements epoll */
        epoll_data_t data;      /* Variable utilisateur */
    };

note: type: Plain text
en: The I<data> of each returned structure will contain the same data the user set with an B<epoll_ctl>(2)  (B<EPOLL_CTL_ADD>, B<EPOLL_CTL_MOD>)  while the I<events> member will contain the returned event bit field.
fr: Le champ I<data> de la structure renvoyée contiendra les mêmes données que lors de l'appel B<epoll_ctl>(2) (B<EPOLL_CTL_ADD>, B<EPOLL_CTL_MOD>) tandis que le champ I<events> contiendra le masque de bit des événements disponibles.

note: type: Plain text
en: The relationship between B<epoll_wait>()  and B<epoll_pwait>()  is analogous to the relationship between B<select>(2)  and B<pselect>(2): like B<pselect>(2), B<epoll_pwait>()  allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught.
fr: La relation entre B<epoll_wait>() et B<epoll_pwait>() est similaire à celle entre B<select>(2) et B<pselect>(2)\ : de même que B<pselect>(2), B<epoll_pwait>() permet à une application d'attendre de façon sûre qu'un descripteur de fichier soit prêt ou qu'un signal arrive.

note: type: Plain text
en: The following B<epoll_pwait>()  call:
fr: L'appel à B<epoll_pwait>() suivant\ :

note: type: Plain text
en: is equivalent to I<atomically> executing the following calls:
fr: est équivalent à exécuter de façon I<atomique> les appels suivants\ :

note: type: Plain text
en: The I<sigmask> argument may be specified as NULL, in which case B<epoll_pwait>()  is equivalent to B<epoll_wait>().
fr: Le paramètre I<sigmask> peut valoir NULL, auquel cas, B<epoll_pwait>() est équivalent à B<epoll_wait>().

note: type: Plain text
en: When successful, B<epoll_wait>()  returns the number of file descriptors ready for the requested I/O, or zero if no file descriptor became ready during the requested I<timeout> milliseconds.  When an error occurs, B<epoll_wait>()  returns -1 and I<errno> is set appropriately.
fr: Lorsqu'il réussit, l'appel B<epoll_wait>() renvoie le nombre de descripteurs prêts pour les E/S demandées, ou zéro si aucun descripteur n'est devenu prêt pendant la durée I<timeout> millisecondes. Si une erreur se produit, B<epoll_wait>() renvoie -1 et I<errno> contient le code approprié.

note: type: Plain text
en: I<epfd> is not a valid file descriptor.
fr: I<epfd> n'est pas un descripteur de fichier valable.

note: type: Plain text
en: The memory area pointed to by I<events> is not accessible with write permissions.
fr: La zone mémoire pointée par I<events> n'est pas accessible en écriture.

note: type: Plain text
en: The call was interrupted by a signal handler before either (1) any of the requested events occurred or (2) the I<timeout> expired; see B<signal>(7).
fr: L'appel a été interrompu par un signal avant, soit qu'aucun des événements demandés n'ait lieu, soit que la temporisation I<timeout> n'expire ; consultez B<signal>(7).

note: type: Plain text
en: I<epfd> is not an B<epoll> file descriptor, or I<maxevents> is less than or equal to zero.
fr: Le descripteur I<epfd> fourni n'est pas un descripteur B<epoll>, ou le paramètre I<maxevents> est inférieur ou égal à zéro.

note: To be precise: kernel 2.5.44. The interface should be finalized by Linux kernel 2.5.66. type: Plain text
en: B<epoll_wait>()  was added to the kernel in version 2.6.  Library support is provided in glibc starting with version 2.3.2.
fr: B<epoll_wait> a été introduite dans le noyau Linux 2.6. La prise en charge par la glibc a été ajoutée dans la version 2.3.2.

note: type: Plain text
en: B<epoll_pwait>()  was added to Linux in kernel 2.6.19.  Library support is provided in glibc starting with version 2.6.
fr: B<epoll_pwait> a été introduite dans le noyau Linux 2.6.19. La prise en charge par la glibc a été ajoutée dans la version 2.6.

note: type: Plain text
en: B<epoll_wait>()  is Linux-specific.
fr: B<epoll_wait>() est spécifique à Linux.

note: type: Plain text
en: While one thread is blocked in a call to B<epoll_pwait>(), it is possible for another thread to add a file descriptor to the waited-upon B<epoll> instance.  If the new file descriptor becomes ready, it will cause the B<epoll_wait>()  call to unblock.
fr: Alors qu'un thread est bloqué par un appel de B<epoll_pwait>(), un autre thread pourrait ajouter un descripteur de fichier à l'instance B<epoll> attendue. Si le nouveau descripteur de fichier devient prêt, il forcera le déblocage de l'appel B<epoll_wait>().

note: type: Plain text
en: For a discussion of what may happen if a file descriptor in an B<epoll> instance being monitored by B<epoll_wait>()  is closed in another thread, see B<select>(2).
fr: Consultez B<select>(2) pour une discussion sur ce qui pourrait arriver si un descripteur de fichier, dans une instance B<epoll>, surveillé par B<epoll_wait>() est fermé dans un autre thread.

note: type: Plain text
en: In kernels before 2.6.37, a I<timeout> value larger than approximately I<LONG_MAX / HZ> milliseconds is treated as -1 (i.e., infinity).  Thus, for example, on a system where the I<sizeof(long)> is 4 and the kernel I<HZ> value is 1000, this means that timeouts greater than 35.79 minutes are treated as infinity.
fr: Dans les noyaux jusqu'à la version 2.6.37, une valeur I<timeout> plus grande qu'environ I<LONG_MAX / HZ> millisecondes est traitée comme -1 (c'est-à-dire l'infini). Ainsi, par exemple, sur un système où I<sizeof(long)> est 4 et la valeur I<HZ> du noyau est 1000, cela signifie que les temps d'attente supérieurs à 35,79 minutes sont traités comme l'infini.

note: type: Plain text
en: poll, ppoll - wait for some event on a file descriptor
fr: poll, ppoll - Attendre un événement concernant un descripteur de fichier

note: type: Plain text
en: B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */
    B<#include E<lt>poll.hE<gt>>
fr: B<#define _GNU_SOURCE>         /* Consultez feature_test_macros(7) */
    B<#include E<lt>poll.hE<gt>>

note: type: Plain text
en: B<poll>()  performs a similar task to B<select>(2): it waits for one of a set of file descriptors to become ready to perform I/O.
fr: B<poll>() est une variation sur le thème de B<select>(2)\ : il attend que l'un des descripteurs de fichier soit prêt pour des entrées-sorties.

note: type: Plain text
en: The set of file descriptors to be monitored is specified in the I<fds> argument, which is an array of structures of the following form:
fr: L'ensemble de descripteurs de fichier à surveiller est indiqué dans l'argument I<fds>, qui est un tableau de structures de la forme suivante\ :

note: type: Plain text
en: struct pollfd {
        int   fd;         /* file descriptor */
        short events;     /* requested events */
        short revents;    /* returned events */
    };
fr: struct pollfd {
        int   fd;         /* Descripteur de fichier */
        short events;     /* Événements attendus    */
        short revents;    /* Événements détectés    */
    };

note: type: Plain text
en: The caller should specify the number of items in the I<fds> array in I<nfds>.
fr: L'appelant doit spécifier le nombre d'élément du tableau I<fds> dans I<nfds>.

note: type: Plain text
en: The field I<fd> contains a file descriptor for an open file.  If this field is negative, then the corresponding I<events> field is ignored and the I<revents> field returns zero.  (This provides an easy way of ignoring a file descriptor for a single B<poll>()  call: simply negate the I<fd> field.)
fr: Le champ I<fd> contient un descripteur de fichier pour un fichier ouvert. Si ce champ est négatif, alors le champ I<events> correspondant est ignoré et le champ I<revents> renvoie zéro (cela permet d'ignorer facilement un descripteur de fichier pour un seul appel B<poll>() : il suffit d'utiliser l'opposé du champ I<fd>).

note: type: Plain text
en: The field I<events> is an input parameter, a bit mask specifying the events the application is interested in for the file descriptor I<fd>.  This field may be specified as zero, in which case the only events that can be returned in I<revents> are B<POLLHUP>, B<POLLERR>, and B<POLLNVAL> (see below).
fr: Le champ I<events> est un paramètre d'entrée, un masque de bits indiquant les événements qui intéressent l'application pour le descripteur de fichier I<fd>. Ce champ peut être nul, auquel cas les seuls événements qui peuvent être renvoyés dans I<revents> sont B<POLLHUP>, B<POLLERR> et B<POLLNVAL> (voir ci-dessous).

note: type: Plain text
en: The field I<revents> is an output parameter, filled by the kernel with the events that actually occurred.  The bits returned in I<revents> can include any of those specified in I<events>, or one of the values B<POLLERR>, B<POLLHUP>, or B<POLLNVAL>.  (These three bits are meaningless in the I<events> field, and will be set in the I<revents> field whenever the corresponding condition is true.)
fr: Le champ I<revents> est un paramètre de sortie, rempli par le noyau avec les événements qui se sont effectivement produits, d'un des types demandés par I<events>, ou de l'une des valeurs B<POLLERR>, B<POLLHUP> ou B<POLLNVAL>. (Ces trois bits n'ont pas de signification dans la demande I<events>, et se trouvent positionnés dans la valeur de retour I<revents> si l'une des conditions correspondantes se produit.)

note: type: Plain text
en: If none of the events requested (and no error) has occurred for any of the file descriptors, then B<poll>()  blocks until one of the events occurs.
fr: Si aucun événement attendu (ni aucune erreur) ne s'est déjà produit, B<poll>() bloque jusqu'à ce que l'un des événements se produise.

note: type: Plain text
en: The I<timeout> argument specifies the number of milliseconds that B<poll>()  should block waiting for a file descriptor to become ready.  The call will block until either:
fr: L'argument I<timeout> définit le temps en milliseconde pendant lequel B<poll>() devrait bloquer en attendant que le descripteur de fichier soit prêt. L’appel bloquera jusqu’au premier événement suivant :

note: type: Plain text
en: a file descriptor becomes ready;
fr: un descripteur de fichier devient prêt ;

note: type: Plain text
en: the timeout expires.
fr: le délai expire.

note: type: Plain text
en: Note that the I<timeout> interval will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.  Specifying a negative value in I<timeout> means an infinite timeout.  Specifying a I<timeout> of zero causes B<poll>()  to return immediately, even if no file descriptors are ready.
fr: Remarquez que l’intervalle I<timeout> sera arrondi à la granularité de l'horloge système et que les délais d'ordonnancement du noyau signifient que l'intervalle de blocage pourrait être dépassé d'une petite quantité. Une valeur négative de I<timeout> signifie un délai infini, alors qu'un I<timeout> nul force B<epoll>() à se terminer immédiatement, même si aucun descripteur de fichier n'est prêt.

note: type: Plain text
en: The bits that may be set/returned in I<events> and I<revents> are defined in I<E<lt>poll.hE<gt>>:
fr: Les bits qui peuvent être activés ou renvoyés dans I<events> et I<revents> sont définis par I<E<lt>poll.hE<gt>>\ :

note: type: Plain text
en: There is data to read.
fr: Il y a des données en attente de lecture.

note: type: Plain text
en: There is urgent data to read (e.g., out-of-band data on TCP socket; pseudoterminal master in packet mode has seen state change in slave).
fr: Il y a des données urgentes en attente de lecture (par exemple, des données hors bande sur une socket TCP, ou bien un pseudoterminal maître en mode paquet constatant un changement d'état de l'esclave).

note: type: Plain text
en: Writing now will not block.
fr: Une écriture ne bloquera pas.

note: type: TP
en: B<POLLRDHUP> (since Linux 2.6.17)
fr: B<POLLRDHUP> (depuis Linux 2.6.17)

note: type: Plain text
en: Stream socket peer closed connection, or shut down writing half of connection.  The B<_GNU_SOURCE> feature test macro must be defined (before including I<any> header files)  in order to obtain this definition.
fr: Le correspondant sur une socket en mode flux a fermé la connexion, ou bien a terminé la partie écriture de la connexion. La macro de test de fonctionnalité B<_GNU_SOURCE> doit être définie (avant d'inclure I<tout> fichier d'en\(hytête) pour obtenir cette définition.

note: type: Plain text
en: Error condition (output only).
fr: Condition d'erreur (uniquement en sortie).

note: type: Plain text
en: Hang up (output only).
fr: Le correspondant a fermé la connexion (uniquement en sortie).

note: type: Plain text
en: Invalid request: I<fd> not open (output only).
fr: Requête invalide\ : I<fd> n'est pas ouvert (uniquement en sortie).

note: type: Plain text
en: When compiling with B<_XOPEN_SOURCE> defined, one also has the following, which convey no further information beyond the bits listed above:
fr: Lorsque B<_XOPEN_SOURCE> est défini à la compilation, les macros suivantes sont également définies (mais n'apportent pas d'informations supplémentaires par rapport aux bits listés ci\(hydessus\ :

note: type: Plain text
en: Equivalent to B<POLLIN>.
fr: Équivalent à B<POLLIN>.

note: POLLRDBAND is used in the DECnet protocol. type: Plain text
en: Priority band data can be read (generally unused on Linux).
fr: Des données prioritaires sont en attente de lecture (généralement inutilisé sous Linux).

note: type: Plain text
en: Equivalent to B<POLLOUT>.
fr: Équivalent à B<POLLOUT>.

note: type: Plain text
en: Priority data may be written.
fr: Des données prioritaires peuvent être écrites.

note: type: Plain text
en: Linux also knows about, but does not use B<POLLMSG>.
fr: Linux connaît aussi B<POLLMSG>, mais ne l'utilise pas.

note: type: Plain text
en: The relationship between B<poll>()  and B<ppoll>()  is analogous to the relationship between B<select>(2)  and B<pselect>(2): like B<pselect>(2), B<ppoll>()  allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught.
fr: La relation entre B<poll>() et B<ppoll>() est similaire à la relation entre B<select>(2) et B<pselect>(2)\ : de même que B<pselect>(2), B<ppoll>() permet à une application d'attendre de façon sûre que soit un descripteur de fichier soit prêt, soit un signal soit reçu.

note: type: Plain text
en: Other than the difference in the precision of the I<timeout> argument, the following B<ppoll>()  call:
fr: Mise à part la différence de précision de l'argument I<timeout>, l'appel B<ppoll>() suivant\ :

note: type: Plain text
en: See the description of B<pselect>(2)  for an explanation of why B<ppoll>()  is necessary.
fr: Consultez la description de B<pselect>(2) pour une explication de la nécessité de B<ppoll>().

note: type: Plain text
en: If the I<sigmask> argument is specified as NULL, then no signal mask manipulation is performed (and thus B<ppoll>()  differs from B<poll>()  only in the precision of the I<timeout> argument).
fr: Si le paramètre I<sigmask> est défini comme NULL, aucune manipulation de masque de signaux n'est effectuée (et ainsi B<ppoll>() ne diffère de B<poll>() que dans la précision du paramètre I<timeout>).

note: type: Plain text
en: The I<timeout_ts> argument specifies an upper limit on the amount of time that B<ppoll>()  will block.  This argument is a pointer to a structure of the following form:
fr: L'argument I<timeout_ts> définit une limite supérieure sur le temps pendant lequel B<ppoll>() bloquera. Cet argument est pointe vers une structure de la forme suivante\ :

note: type: Plain text
en: struct timespec {
        long    tv_sec;         /* seconds */
        long    tv_nsec;        /* nanoseconds */
    };
fr: struct timespec {
        long    tv_sec;         /* secondes     */
        long    tv_nsec;        /* nanosecondes */
    };

note: type: Plain text
en: If I<timeout_ts> is specified as NULL, then B<ppoll>()  can block indefinitely.
fr: Si I<timeout_ts> est NULL, B<ppoll>() pourra bloquer indéfiniment.

note: type: Plain text
en: On success, a positive number is returned; this is the number of structures which have nonzero I<revents> fields (in other words, those descriptors with events or errors reported).  A value of 0 indicates that the call timed out and no file descriptors were ready.  On error, -1 is returned, and I<errno> is set appropriately.
fr: En cas de réussite, ces appels renvoient une valeur positive représentant le nombre de structures ayant un champ I<revents> non nul, c'est-à-dire le nombre de structures pour lesquels un événement attendu, ou une erreur, s'est produit. Une valeur de retour nulle indique un dépassement du délai d'attente. En cas d'échec, ils renvoient -1, et I<errno> contient le code d'erreur.

note: type: Plain text
en: The array given as argument was not contained in the calling program's address space.
fr: La table fournie en argument n'est pas dans l'espace d'adressage du processus appelant.

note: type: Plain text
en: A signal occurred before any requested event; see B<signal>(7).
fr: Un signal a été reçu avant qu'un événement intéressant ne se produise ; voir B<signal>(7).

note: type: Plain text
en: The I<nfds> value exceeds the B<RLIMIT_NOFILE> value.
fr: La valeur I<nfds> dépasse la valeur B<RLIMIT_NOFILE>.

note: type: Plain text
en: There was no space to allocate file descriptor tables.
fr: Pas assez de mémoire pour allouer la table des descripteurs de fichier.

note: library call was introduced in libc 5.4.28 type: Plain text
en: The B<poll>()  system call was introduced in Linux 2.1.23.  On older kernels that lack this system call, the glibc (and the old Linux libc)  B<poll>()  wrapper function provides emulation using B<select>(2).
fr: L'appel système B<poll>() a été introduit dans Linux 2.1.23. Sur les anciens noyaux sans cet appel système, la fonction enveloppe B<poll>() de la glibc (et de l'ancienne libc Linux) fournit une émulation en utilisant B<select>(2).

note: type: Plain text
en: The B<ppoll>()  system call was added to Linux in kernel 2.6.16.  The B<ppoll>()  library call was added in glibc 2.4.
fr: L'appel système B<ppoll>() a été introduit dans Linux 2.6.16. La fonction de bibliothèque correspondante a été ajoutée dans la glibc 2.4.

note: NetBSD 3.0 has a pollts() which is like Linux ppoll(). type: Plain text
en: B<poll>()  conforms to POSIX.1-2001.  B<ppoll>()  is Linux-specific.
fr: B<poll>() est conforme à POSIX.1-2001. B<ppoll>() est spécifique à Linux.

note: type: Plain text
en: Some implementations define the nonstandard constant B<INFTIM> with the value -1 for use as a I<timeout> for B<poll>().  This constant is not provided in glibc.
fr: Certaines implémentations définissent la constante symbolique non standard B<INFTIM> de valeur -1, à utiliser comme I<timeout> pour B<poll>(). Cette constante n'est pas fournie par la glibc.

note: type: Plain text
en: For a discussion of what may happen if a file descriptor being monitored by B<poll>()  is closed in another thread, see B<select>(2).
fr: Consultez B<select>(2) pour une discussion sur ce qui pourrait arriver si un descripteur de fichier surveillé par B<poll>() est fermé dans un autre thread.

note: type: SS
en: Linux notes
fr: Notes sur Linux

note: type: Plain text
en: The Linux B<ppoll>()  system call modifies its I<timeout_ts> argument.  However, the glibc wrapper function hides this behavior by using a local variable for the timeout argument that is passed to the system call.  Thus, the glibc B<ppoll>()  function does not modify its I<timeout_ts> argument.
fr: L'appel système B<ppoll>() sous Linux modifie son argument I<timeout_ts>. Cependant, l'enrobage fourni par la glibc cache ce comportement en utilisant une variable locale pour le délai, qui est fournie à l'appel système. La fonction B<ppoll>() de la glibc ne modifie donc pas son argument I<timeout_ts>.

note: type: Plain text
en: See the discussion of spurious readiness notifications under the BUGS section of B<select>(2).
fr: Consultez la discussion sur les notifications non voulues dans la section BOGUES de B<select>(2).
