Provided by: manpages-fr-dev_3.32d0.2p4-1_all bug

NOM

       timerfd_create,   timerfd_settime,  timerfd_gettime  -  Minuteries  qui
       informent par l'intermediaire de descripteurs de fichier

SYNOPSIS

       #include <sys/timerfd.h>

       int timerfd_create(int clockid, int flags);

       int timerfd_settime(int fd, int flags,
                           const struct itimerspec *new_value,
                           struct itimerspec *old_value);

       int timerfd_gettime(int fd, struct itimerspec *curr_value);

DESCRIPTION

       Ces appels systeme creent et operent sur une minuterie qui fournit  des
       notifications   d'expiration   par   un  descripteur  de  fichier.  Ils
       fournissent une alternative  a  setitimer(2)  ou  timer_create(2)  avec
       l'avantage  que  le  descripteur  de  fichier  peut etre surveille avec
       select(2), poll(2) ou epoll(7).

       L'utilisation de ces trois appels systeme est analogue a  l'utilisation
       de timer_create(2), timer_settime(2) et timer_gettime(2). (Il n'y a pas
       d'equivalent a timer_getoverrun(2)  puisque  cette  fonctionnalite  est
       fournie par read(2), comme decrit ci-dessous)

   timerfd_create()
       timerfd_create()  cree  une  minuterie,  et  renvoie  un descripteur de
       fichier qui se refere a cette minuterie. Le parametre clockid  specifie
       l'horloge  qui est utilisee pour faire progresser la minuterie, et doit
       valoir soit CLOCK_REALTIME, soit  CLOCK_MONOTONIC.  CLOCK_REALTIME  est
       une   horloge   configurable  du  systeme.  CLOCK_MONOTONIC  n'est  pas
       configurable,  c'est  a  dire  qu'elle  n'est  pas  affectee  par   des
       modifications  discontinues  de l'horloge systeme (par exemple, par des
       modifications manuelles de l'heure du systeme). L'heure de  chacune  de
       ces horloge peut etre interrogee a l'aide de clock_gettime(2).

       A  partir  de Linux 2.6.27, les valeurs suivantes peuvent etre incluses
       avec  un  OU  binaire  dans  flags  pour  changer  le  comportement  de
       timerfd_create() :

       TFD_NONBLOCK  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.

       TFD_CLOEXEC   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.

       Dans  les  versions  de  Linux jusqu'a la version 2.6.26 incluse, flags
       doit etre nul.

   timerfd_settime()
       timerfd_settime() arme (demarre) ou desarme  (stoppe)  la  minuterie  a
       laquelle se refere le descripteur de fichier fd.

       Le  parametre  new_value specifie l'expiration initiale et l'intervalle
       de la  minuterie.  La  structure  itimer  utilisee  pour  ce  parametre
       contient  deux  champs,  chacun d'entre eux etant une structure de type
       timespec :

           struct timespec {
               time_t tv_sec;                /* Secondes */
               long   tv_nsec;               /* Nanosecondes */
           };

           struct itimerspec {
               struct timespec it_interval;  /* Intervalle pour les
                                                minuteries periodiques */
               struct timespec it_value;     /* Expiration initiale */
           };

       new_value.it_value specifie l'expiration initiale de la  minuterie,  en
       secondes  et  nanosecondes.  Une valeur non nulle dans un des champs de
       new_value.it_value arme la minuterie. La minuterie est desarmee si  les
       deux champs de new_value.it_value sont mis a zero.

       Une  valeur  non  nulle  dans  un  des  champs de new_value.it_interval
       configure la periode, en secondes et nanosecondes, pour une  expiration
       repetitive   apres   l'expiration  initiale.  Si  les  deux  champs  de
       new_value.it_interval sont nuls, la  minuterie  expirera  qu'une  seule
       fois, dont l'heure est specifiee dans new_value.it_value.

       Le   parametre   flags  est  soit  nul,  pour  demarrer  une  minuterie
       << relative >> (new_value.it_interval specifie un temps  relatif  a  la
       valeur    actuelle    de   l'horloge   specifiee   par   clockid),   ou
       TFD_TIMER_ABSTIME,   pour   demarrer   une   minuterie    << absolue >>
       (new_value.it_value  specifie  un temps absolu pour l'horloge specifiee
       par clockid ; c'est-a-dire que la minuterie expirera quand la valeur de
       l'horloge atteindra la valeur specifiee par new_value.it_value).

       Le parametre old_value renvoie une structure contenant la configuration
       de la minuterie au moment de  l'appel ;  consultez  la  description  de
       timerfd_gettime() ci-dessous.

   timerfd_gettime()
       timerfd_gettime()  renvoie,  dans  curr_value, une structure itimerspec
       qui  contient  les  parametres  actuels  de  la  minuterie  auquel   le
       descripteur de fichier fd fait reference.

       Le  champ it_value renvoie la duree jusqu'a la prochaine expiration. Si
       les deux champs de cette structure sont nuls, alors  la  minuterie  est
       actuellement   desactivee.   Ce  champ  contient  toujours  une  valeur
       relative, sans tenir compte d'un attribut TFD_TIMER_ABSTIME qui  aurait
       ete specifie quand la minuterie a ete configuree.

       Le  champ  it_interval  renvoie la periode de la minuterie. Si les deux
       champs de cette structure sont nuls, alors la minuteries est configuree
       pour   n'expirer   qu'une   seule   fois,   a   l'heure  specifiee  par
       curr_value.it_value.

   Op'erations sur un descripteur de fichier de minuterie
       Le  descripteur  de  fichier  renvoye  par  timerfd_create()  gere  les
       operations suivante :

       read(2)
              Si  la  minuterie  a deja expiree une fois ou plus depuis que sa
              configuration a ete  modifiee  la  derniere  fois  a  l'aide  de
              timerfd_settime() ou depuis la derniere lecture avec read(2) qui
              a reussi, alors le tampon fourni a read(2) renvoie un entier non
              signe   sur   8   octets   (uint64_t)  qui  contient  le  nombre
              d'expirations qui se sont produites. (La valeur renvoyee utilise
              l'ordre  des  octets  de l'hote, c'est-a-dire l'ordre des octets
              natif pour les entiers sur la machine hote)

              Si aucune expiration ne s'est produite au moment  de  l'appel  a
              read(2),  l'appel  bloquera  jusqu'a  la prochaine expiration ou
              echouera avec l'erreur EAGAIN si le descripteur de  fichier  est
              en  mode  non  bloquant  (l'operation  fcntl(2)  F_SETFL  a  ete
              utilisee avec un attribut O_NONBLOCK).

              Un read(2) echouera avec l'erreur EINVAL si la taille du  tampon
              fourni est de moins de 8 octets.

       poll(2), select(2) (et similaires)
              Le  descripteur  de fichier est lisible (le parametre readfds de
              select(2) ; l'attribut POLLIN de poll(2)) si une expiration  (ou
              plus) de la minuterie s'est produite.

              Le  descripteur  de fichier 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  minuterie  ont  ete fermes, les ressources pour cet
              objet sont liberees par le noyau.

   S'emantique de fork(2)
       Apres un fork(2), le fils herite d'une copie du descripteur de  fichier
       cree  par  timerfd_create().  Le  descripteur de fichier se refere a la
       meme minuterie sous-jacente que le descripteur de fichier correspondant
       du  pere,  et  un  read(2)  du  fils  renverra  les informations sur la
       minuterie.

   S'emantique de execve(2)
       Un descripteur de fichier cree par  timerfd_create()  est  conserve  au
       travers  d'un  execve(2),  et  continue  a  generer  des expirations de
       minuterie si la minuterie a ete armee.

VALEUR RENVOY'EE

       S'il  reussit,  timerfd_create()  renvoie  un  nouveau  descripteur  de
       fichier.  En  cas  d'erreur,  il  renvoie  -1 et errno contient le code
       d'erreur.

       En cas de reussite, timerfd_settime() et timerfd_gettime() renvoient 0.
       Sinon ils renvoient -1 et errno contient le code d'erreur.

ERREURS

       timerfd_create() peut echouer avec les erreurs suivantes :

       EINVAL Le parametre clockid n'est ni CLOCK_MONOTONIC ni CLOCK_REALTIME;

       EINVAL flags  n'est pas correct ; ou, pour les versions de Linux 2.6.26
              ou ulterieures, flags n'est pas nul.

       EMFILE La limite du nombre total de descripteurs de fichier ouverts par
              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 Pas assez de memoire noyau pour creer la minuterie.

       timerfd_settime() et timerfd_gettime() peuvent echouer avec les erreurs
       suivantes :

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

       EFAULT new_value,  old_value  ou  curr_value  n'est  pas  un   pointeur
              valable.

       EINVAL fd n'est pas un descripteur de fichier de minuterie valable.

       timerfd_settime() peut aussi echouer avec les erreurs suivantes :

       EINVAL new_value  n'est  pas  initialise  correctement  (un  des champs
              tv_nsec est en dehors de l'intervalle allant  de  0  a  999  999
              999).

       EINVAL flags n'est pas correct.

VERSIONS

       Ces  appels systeme sont disponibles sous Linux depuis le noyau 2.6.25.
       La glibc les gere depuis la version 2.8.

CONFORMIT'E

       Ces appels systeme sont specifiques a Linux.

EXEMPLE

       Le programme suivant cree une minuterie puis surveille sa  progression.
       Le  programme accepte jusqu'a trois parametres en ligne de commande. Le
       premier parametre specifie le  nombre  de  secondes  pour  l'expiration
       initiale  de la minuterie. Le deuxieme parametre specifie la periode de
       la minuterie, en secondes. Le troisieme parametre specifie le nombre de
       fois  que le programme doit permettre a la minuterie d'expirer avant de
       quitter. Le deuxieme et le troisieme parametre sont optionnels.

       La session interactive suivante montre l'utilisation de ce programme :

           $ a.out 3 1 100
           0.000: timer started
           3.000: read: 1; total=1
           4.000: read: 1; total=2
           ^Z                  # type control-Z to suspend the program
           [1]+  Stopped                 ./timerfd3_demo 3 1 100
           $ fg                # Resume execution after a few seconds
           a.out 3 1 100
           9.660: read: 5; total=7
           10.000: read: 1; total=8
           11.000: read: 1; total=9
           ^C                  # type control-C to suspend the program

   Source du programme

       #include <sys/timerfd.h>
       #include <time.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)

       static void
       print_elapsed_time(void)
       {
           static struct timespec start;
           struct timespec curr;
           static int first_call = 1;
           int secs, nsecs;

           if (first_call) {
               first_call = 0;
               if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
                   handle_error("clock_gettime");
           }

           if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
               handle_error("clock_gettime");

           secs = curr.tv_sec - start.tv_sec;
           nsecs = curr.tv_nsec - start.tv_nsec;
           if (nsecs < 0) {
               secs--;
               nsecs += 1000000000;
           }
           printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
       }

       int
       main(int argc, char *argv[])
       {
           struct itimerspec new_value;
           int max_exp, fd;
           struct timespec now;
           uint64_t exp, tot_exp;
           ssize_t s;

           if ((argc != 2) && (argc != 4)) {
               fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           if (clock_gettime(CLOCK_REALTIME, &now) == -1)
               handle_error("clock_gettime");

           /* Create a CLOCK_REALTIME absolute timer with initial
              expiration and interval as specified in command line */

           new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
           new_value.it_value.tv_nsec = now.tv_nsec;
           if (argc == 2) {
               new_value.it_interval.tv_sec = 0;
               max_exp = 1;
           } else {
               new_value.it_interval.tv_sec = atoi(argv[2]);
               max_exp = atoi(argv[3]);
           }
           new_value.it_interval.tv_nsec = 0;

           fd = timerfd_create(CLOCK_REALTIME, 0);
           if (fd == -1)
               handle_error("timerfd_create");

           if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
               handle_error("timerfd_settime");

           print_elapsed_time();
           printf("timer started\n");

           for (tot_exp = 0; tot_exp < max_exp;) {
               s = read(fd, &exp, sizeof(uint64_t));
               if (s != sizeof(uint64_t))
                   handle_error("read");

               tot_exp += exp;
               print_elapsed_time();
               printf("read: %llu; total=%llu\n",
                       (unsigned long long) exp,
                       (unsigned long long) tot_exp);
           }

           exit(EXIT_SUCCESS);
       }

BOGUES

       Actuellement,  timerfd_create()  prend  en   charge   moins   de   type
       d'identifiants d'horloges que timer_create(2).

VOIR AUSSI

       eventfd(2),  poll(2),  read(2),  select(2),  setitimer(2), signalfd(2),
       timer_create(2), timer_gettime(2), timer_settime(2), epoll(7), time(7)

COLOPHON

       Cette page fait partie de  la  publication  3.32  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> >>.