Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

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)