Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
eventfd - Creer un descripteur de fichier pour la notification
d'evenements
SYNOPSIS
#include <sys/eventfd.h>
int eventfd(unsigned int initval, int flags);
DESCRIPTION
eventfd() creee un << objet eventfd >> qui peut etre utilise par les
applications de l'espace utilisateur pour l'attente ou la notification
d'un evenement et par le noyau pour notifier des applications de
certains evenements. Les objets contiennent un compteur entier non
signe sur 64 bits (uint64_t) qui est maintenu par le noyau. Ce compteur
est initialise a la valeur specifiee par le parametre initval.
Les valeurs suivantes peuvent etre incluses (avec un OU logique) dans
flags pour changer le comportement de eventfd() :
EFD_CLOEXEC (depuis Linux 2.6.27)
Placer l'attribut << close-on-exec >> (FD_CLOEXEC) sur le
nouveau descripteur de fichier. Consultez la description de
l'attribut O_CLOEXEC dans open(2) pour savoir pourquoi cela peut
etre utile.
EFD_NONBLOCK (depuis Linux 2.6.27)
Placer l'attribut d'etat de fichier O_NONBLOCK sur le nouveau
descripteur de fichier ouvert. Utiliser cet attribut economise
des appels supplementaires a fcntl(2) pour obtenir le meme
resultat.
EFD_SEMAPHORE (depuis Linux 2.6.30)
Fournir une semantique similaire aux semaphores pour les
lectures sur le nouveau descripteur de fichier. Voir ci-dessous.
Dans les versions de Linux jusqu'a la version 2.6.26, le parametre
flags n'est pas utilise et doit valoir zero.
Comme valeur de retour, eventfd() renvoie un nouveau descripteur de
fichier qui peut etre utilise pour se referer a l'objet eventfd. Les
operations suivantes peuvent etre effectuees sur le descripteur de
fichier :
read(2)
Chaque read(2) qui reussit renvoie un entier sur 8 octets.
read(2) echouera avec l'erreur EINVAL si la taille du tampon
fourni est de moins de 8 octets.
La valeur renvoyee par read(2) utilise l'ordre des octets de
l'hote, c'est-a-dire l'ordre des octets natif pour les entiers
sur la machine hote.
La semantique de read(2) depend du fait que le compteur eventfd
a actuellement une valeur non nulle, et que l'attribut
EFD_SEMAPHORE etait specifie lors de la creation du descripteur
de fichier eventfd :
* Si EFD_SEMAPHORE n'etait pas specifie et si le compteur
eventfd a une valeur non nulle, un read(2) renverra 8 octets
contenant cette valeur, et la valeur du compteur sera remise
a zero.
* Si EFD_SEMAPHORE etait specifie et si le compteur eventfd a
une valeur non nulle, un read(2) renverra 8 octets contenant
la valeur 1, et la valeur du compteur sera decrementee de 1.
* Si le compteur eventfd est nul au moment de l'appel a
read(2), l'appel bloquera jusqu'a ce que le compteur devienne
non nul (auquel cas l'appel a read(2) sera traite comme
decrit ci-dessus), ou echouera avec l'erreur EAGAIN si le
descripteur de fichier est en mode non bloquant.
write(2)
Un appel a write(2) ajoute au compteur la valeur de l'entier sur
8 octets fourni dans le tampon. La valeur maximale qui peut etre
stockee dans le compteur est le plus grand entier non signe sur
64 bits moins 1 (c'est-a-dire 0xfffffffffffffffe). Si l'addition
resulte en un compteur qui depasserait la valeur maximale, le
write(2) bloquera jusqu'a ce qu'un read(2) soit effectue sur le
descripteur de fichier, ou echouera avec l'erreur EAGAIN si le
descripteur de fichier est en mode non bloquant.
Un write(2) echouera avec l'erreur EINVAL si la taille du tampon
fourni est de moins de 8 octets ou si l'on essaie d'ecrire la
valeur 0xffffffffffffffff.
poll(2), select(2) (et similaires)
Le descripteur de fichier prend en charge les poll(2) (et de
facon analogue epoll(7)) et select(2) de la facon suivante :
* Le descripteur de fichier est lisible (le parametre readfds
de select(2) ; l'attribut POLLIN de poll(2)) si le compteur a
une valeur superieure a 0.
* Le descripteur de fichier est disponible en ecriture (le
parametre writefds de select(2) ; l'attribut POLLOUT de
poll(2)) s'il est possible d'ecrire une valeur d'au moins
<< 1 >> sans bloquer.
* Si un depassement de la valeur du compteur a ete detectee,
select(2) indique que le descripteur de fichier est
disponible en lecture et en ecriture et poll(2) renvoie un
evenement POLLERR. Comme indiquee ci-dessus, un write(2) ne
peut jamais produire de depassement. Cependant, un
depassement peut se produire si un << signal post >> eventfd
de 2^64 a ete effectue par le sous-systeme KAIO
(theoriquement possible, mais tres peut probable en
pratique). Si un depassement survient, un read(2) renverra la
valeur maximale d'un uint64_t (c'est-a-dire
0xffffffffffffffff).
Le descripteur de fichier eventfd prend egalement en charge les
autres interfaces de multiplexage de descripteurs de fichier :
pselect(2), ppoll(2) et epoll(7).
close(2)
Quand le descripteur de fichier n'est plus necessaire il doit
etre ferme. Quand tous les descripteurs de fichier associes au
meme objet eventfd ont ete fermes, les ressources pour cet objet
sont liberees par le noyau.
Une copie d'un descripteur de fichier cree par eventfd() est heritee
par le fils produit par fork(2). Le duplicata du descripteur de fichier
est associe au meme objet eventfd. Les descripteurs de fichier crees
par eventfd() sont preserves au travers des executions par execve(2),
sauf si l'attribut << close-on-exec >> est positionne.
VALEUR RENVOY'EE
S'il reussit, eventfd() renvoie un nouveau descripteur de fichier
eventfd. En cas d'erreur, il renvoie -1 et remplit errno avec la valeur
d'erreur.
ERREURS
EINVAL Une valeur non prise en compte a ete specifiee dans flags.
EMFILE La limite des descripteurs ouverts pour le processus a ete
atteinte.
ENFILE La limite du nombre total de fichiers ouverts sur le systeme a
ete atteinte.
ENODEV Impossible de monter (en interne) le peripherique anonyme
d'inoeud.
ENOMEM Il n'y a pas assez de memoire pour que le noyau cree le nouveau
descripteur de fichier eventfd.
VERSIONS
eventfd() est disponible sous Linux depuis le noyau 2.6.22. Le support
fonctionnel est fourni par la glibc depuis la version 2.8. L'appel
systeme eventfd2() (consultez les NOTES) est disponible sous Linux
depuis le noyau 2.6.27. Depuis la version 2.9, la fonction enveloppe de
la glibc pour eventfd() utilise l'appel systeme eventfd2() s'il est
pris en charge par le noyau.
CONFORMIT'E
eventfd() et eventfd2() sont specifiques a Linux.
NOTES
Les applications peuvent utiliser un descripteur de fichier eventfd a
la place d'un tube (consultez pipe(2)) a chaque fois qu'un tube est
utilise pour signaler des evenements. La surcharge du noyau pour un
descripteur de fichier est bien plus faible que pour un tube. De plus
un seul descripteur de fichier est necessaire (alors que deux sont
necessaires pour un tube).
Quand un descripteur de fichier eventfd est utilise par le noyau, il
peut fournir un pont entre l'espace utilisateur et l'espace noyau. Par
exemple, les fonctionnalites comme KAIO (<< kernel AIO >>) pour
signaler dans un descripteur de fichier que certaines operations sont
finies.
Un aspect important d'un descripteur de fichier eventfd est qu'il peut
etre surveille comme n'importe quel descripteur de fichier avec
select(2), poll(2) ou epoll(7). Ceci signifie qu'une application peut
surveiller simultanement la disponibilite de fichiers
<< traditionnels >> et la disponibilite de mecanismes noyau qui gerent
une interface eventfd. (Sans l'interface eventfd(), ces mecanismes ne
pouvaient pas etre multiplexes avec select(2), poll(2) ou epoll(7))
Appels syst`eme Linux sous-jacents
Il y a deux appels systeme sous-jacent : eventfd() et eventfd2(), plus
recent. Le premier appel systeme n'implemente pas le parametre flags.
Le dernier appel systeme implemente les valeurs de flags decrite
ci-dessus. La fonction enveloppe de la glibc utilisera eventfd2() quand
il est present.
Fonctionnalit'es suppl'ementaires de la glibc
La bibliotheque C de GNU definie un type supplementaire et deux
fonctions qui tentent d'abstraire certains details pour la lecture ou
l'ecriture avec des descripteurs de fichier eventfd :
typedef uint64_t eventfd_t;
int eventfd_read(int fd, eventfd_t *value);
int eventfd_write(int fd, eventfd_t value);
Les fonctions effectuent des actions de lecture ou ecriture sur le
descripteur de fichier eventfd, en renvoyant 0 si un nombre correct
d'octets a ete transfere, ou -1 sinon.
EXEMPLE
Le programme suivant cree un descripteur de fichier eventfd puis cree
un processus fils. Alors que le pere commence par s'endormir, le fils
ecrit tous les entiers fournis sur la ligne de commande au descripteur
de fichier eventfd. Quand le pere se reveille, il lit dans le
descripteur de fichier eventfd.
La session shell suivante montre un exemple d'execution du programme :
$ ./a.out 1 2 4 7 14
Child writing 1 to efd
Child writing 2 to efd
Child writing 4 to efd
Child writing 7 to efd
Child writing 14 to efd
Child completed write loop
Parent about to read
Parent read 28 (0x1c) from efd
Source du programme
#include <sys/eventfd.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdint.h> /* Definition de uint64_t */
#define handle_error(msg) \
do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{
int efd, j;
uint64_t u;
ssize_t s;
if (argc < 2) {
fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
exit(EXIT_FAILURE);
}
efd = eventfd(0, 0);
if (efd == -1)
handle_error("eventfd");
switch (fork()) {
case 0:
for (j = 1; j < argc; j++) {
printf("Child writing %s to efd\n", argv[j]);
u = strtoull(argv[j], NULL, 0);
/* strtoull() allows various bases */
s = write(efd, &u, sizeof(uint64_t));
if (s != sizeof(uint64_t))
handle_error("write");
}
printf("Child completed write loop\n");
exit(EXIT_SUCCESS);
default:
sleep(2);
printf("Parent about to read\n");
s = read(efd, &u, sizeof(uint64_t));
if (s != sizeof(uint64_t))
handle_error("read");
printf("Parent read %llu (0x%llx) from efd\n",
(unsigned long long) u, (unsigned long long) u);
exit(EXIT_SUCCESS);
case -1:
handle_error("fork");
}
}
VOIR AUSSI
futex(2), pipe(2), poll(2), read(2), select(2), signalfd(2),
timerfd_create(2), write(2), epoll(7), sem_overview(7)
COLOPHON
Cette page fait partie de la publication 3.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Julien Cristau et l'equipe francophone de traduction de
Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.
Linux 30 aout 2010 EVENTFD(2)