Provided by: manpages-fr-dev_3.17.1-1_all bug

NOM

       timerfd_create,   timerfd_settime,  timerfd_gettime  -  Minuteries  qui
       informent par l’intermédiaire 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 *curr_value);

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

DESCRIPTION

       Ces appels système créent et opèrent sur une minuterie qui fournit  des
       notifications   d’expiration   par   un  descripteur  de  fichier.  Ils
       fournissent une alternative  à  setitimer(2)  ou  timer_create(3)  avec
       l’avantage  que  le  descripteur  de  fichier  peut être surveillé avec
       select(2), poll(2) ou epoll(7).

       L’utilisation de ces trois appels système est analogue à  l’utilisation
       de timer_create(3), timer_settime(3) et timer_gettime(3). (Il n’y a pas
       d’équivalent à timer_getoverrun(3)  puisque  cette  fonctionnalité  est
       fournie par read(2), comme décrit ci-dessous)

   timerfd_create()
       timerfd_create()  crée  une  minuterie,  et  renvoie  un descripteur de
       fichier qui se réfère à cette minuterie. Le paramètre clockid  spécifie
       l’horloge  qui est utilisée pour faire progresser la minuterie, et doit
       valoir soit CLOCK_REALTIME, soit  CLOCK_MONOTONIC.  CLOCK_REALTIME  est
       une   horloge   configurable  du  système.  CLOCK_MONOTONIC  n’est  pas
       configurable,  c’est  à  dire  qu’elle  n’est  pas  affectée  par   des
       modifications  discontinues  de l’horloge système (par exemple, par des
       modifications manuelles de l’heure du système). L’heure de  chacune  de
       ces horloge peut être interrogée à l’aide de clock_gettime(3).

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

       TFD_NONBLOCK  Placer  l’attribut  d’état  de  fichier O_NONBLOCK sur le
                     nouveau  descripteur  de  fichier  ouvert.  Utiliser  cet
                     attribut  économise des appels supplémentaires à fcntl(2)
                     pour obtenir le même résultat.

       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
                     ça peut être utile.

       Dans  les  versions  de  Linux jusqu’à la version 2.6.26 incluse, flags
       doit être nul.

   timerfd_settime()
       timerfd_settime() arme (démarre) ou désarme  (stoppe)  la  minuterie  à
       laquelle se réfère le descripteur de fichier fd.

       Le  paramètre  new_value spécifie l’expiration initiale et l’intervalle
       de la  minuterie.  La  structure  itimer  utilisée  pour  ce  paramètre
       contient  deux  champs,  chacun d’entre eux étant 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 périodiques */
               struct timespec it_value;     /* Expiration initiale */
           };

       new_value.it_value spécifie 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 désarmée si  les
       deux champs de new_value.it_value sont mis à zéro.

       Une  valeur  non  nulle  dans  un  des  champs de new_value.it_interval
       configure la période, en secondes et nanosecondes, pour une  expiration
       répétitive   après   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 spécifiée dans new_value.it_value.

       Le   paramètre   flags  est  soit  nul,  pour  démarrer  une  minuterie
       « relative » (new_value.it_interval spécifie  un  temps  relatif  à  la
       valeur    actuelle    de   l’horloge   spécifiée   par   clockid),   ou
       TFD_TIMER_ABSTIME,   pour   démarrer    une    minuterie    « absolue »
       (new_value.it_value  spécifie  un temps absolu pour l’horloge spécifiée
       par clockid ; c’est-à-dire que la minuterie expirera quand la valeur de
       l’horloge atteindra la valeur spécifiée par new_value.it_value).

       Le   paramètre   curr_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  paramètres  actuels  de  la  minuterie  auquel   le
       descripteur de fichier fd fait référence.

       Le  champ it_value renvoie la durée jusqu’à la prochaine expiration. Si
       les deux champs de cette structure sont nuls, alors  la  minuterie  est
       actuellement   désactivée.   Ce  champ  contient  toujours  une  valeur
       relative, sans tenir compte d’un attribut TFD_TIMER_ABSTIME qui  aurait
       été spécifié quand la minuterie a été configurée.

       Le  champ  it_interval  renvoie la période de la minuterie. Si les deux
       champs de cette structure sont nuls, alors la minuteries est configurée
       pour   n’expirer   qu’une   seule   fois,   à   l’heure  spécifiée  par
       curr_value.it_value.

   Opérations sur un descripteur de fichier de minuterie
       Le  descripteur  de  fichier  renvoyé  par  timerfd_create()  gère  les
       opérations suivante :

       read(2)
              Si  la  minuterie  a déjà expirée une fois ou plus depuis que sa
              configuration a été  modifiée  la  dernière  fois  à  l’aide  de
              timerfd_settime() ou depuis la dernière lecture avec read(2) qui
              a réussi, alors le tampon fourni à read(2) renvoie un entier non
              signé   sur   8   octets   (uint64_t)  qui  contient  le  nombre
              d’expirations qui se sont produites. (La valeur renvoyée utilise
              l’ordre  des  octets  de l’hôte, c’est-à-dire l’ordre des octets
              natif pour les entiers sur la machine hôte)

              Si aucune expiration ne s’est produite au moment  de  l’appel  à
              read(2),  l’appel  bloquera  jusqu’à  la prochaine expiration ou
              échouera avec l’erreur EAGAIN si le descripteur de  fichier  est
              en  mode  non  bloquant  (l’opération  fcntl(2)  F_SETFL  a  été
              utilisée avec un attribut O_NONBLOCK).

              Un read(2) échouera 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 paramètre 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 également 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 nécessaire il doit
              être fermé. Quand tous les descripteurs de fichier  associés  au
              même  objet  minuterie  ont  été fermés, les ressources pour cet
              objet sont libérées par le noyau.

   Sémantique de fork(2)
       Après un fork(2), le fils hérite d’une copie du descripteur de  fichier
       créé  par  timerfd_create().  Le  descripteur de fichier se réfère à la
       même minuterie sous-jacente que le descripteur de fichier correspondant
       du  père,  et  un  read(2)  du  fils  renverra  les informations sur la
       minuterie.

   Sémantique de execve(2)
       Un descripteur de fichier créé par  timerfd_create()  est  conservé  au
       travers  d’un  execve(2),  et  continue  à  générer  des expirations de
       minuterie si la minuterie a été armée.

VALEUR RENVOYÉE

       S’il  réussit,  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 réussite, timerfd_settime() et timerfd_gettime() renvoient 0.
       Sinon ils renvoient -1 et errno contient le code d’erreur.

ERREURS

       timerfd_create() peut échouer avec les erreurs suivantes :

       EINVAL Le paramètre 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 ultérieures, flags n’est pas nul.

       EMFILE La limite du nombre total de descripteurs de fichier ouverts par
              processus a été atteinte.

       ENFILE La limite du nombre total de fichiers ouverts sur le  système  a
              été atteinte.

       ENODEV Impossible  de  monter  (en  interne)  le  périphérique  anonyme
              d’inoeud.

       ENOMEM Pas assez de mémoire noyau pour créer la minuterie.

       timerfd_settime() et timerfd_gettime() peuvent échouer avec les erreurs
       suivantes :

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

       EINVAL fd  n’est  pas  un  descripteur de fichier de minuterie valable.
              new_value n’est  pas  initialisé  correctement  (un  des  champs
              tv_nsec  est  en  dehors  de  l’intervalle allant de 0 à 999 999
              999).

VERSIONS

       Ces appels système sont disponibles sous Linux depuis le noyau  2.6.25.
       La glibc les gère depuis la version 2.8.

CONFORMITÉ

       Ces appels système sont spécifiques à Linux.

EXEMPLE

       Le  programme suivant crée une minuterie puis surveille sa progression.
       Le programme accepte jusqu’à trois paramètres en ligne de commande.  Le
       premier  paramètre  spécifie  le  nombre  de secondes pour l’expiration
       initiale de la minuterie. Le deuxième paramètre spécifie la période  de
       la minuterie, en secondes. Le troisième paramètre spécifie le nombre de
       fois que le programme doit permettre à la minuterie d’expirer avant  de
       quitter. Le deuxième et le troisième paramètre 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>        /* Définition 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);
       }

VOIR AUSSI

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

COLOPHON

       Cette page fait partie de  la  publication  3.17  du  projet  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/.

TRADUCTION

       Cette page de manuel a été traduite et est maintenue par Julien Cristau
       <julien.cristau@ens-lyon.org> et l’équipe francophone de traduction  de
       Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».