Provided by: manpages-fr-dev_4.13-4_all bug

NOM

       timer_create - Créer une minuterie POSIX pour un processus

SYNOPSIS

       #include <signal.h>
       #include <time.h>

       int timer_create(clockid_t clockid, struct sigevent *sevp,
                        timer_t *timerid);

       Éditer les liens avec -lrt.

   Exigences    de    macros    de   test   de   fonctionnalités   pour   la   glibc   (consulter
   feature_test_macros(7)) :

       timer_create() : _POSIX_C_SOURCE >= 199309L

DESCRIPTION

       timer_create() crée une nouvelle minuterie  pour  un  processus.  L'identifiant  de  cette
       nouvelle  minuterie  est  renvoyé  dans  le  tampon  pointé  par timerid, qui doit être un
       pointeur différent de NULL. L'identifiant est unique pour le processus, jusqu'à ce que  la
       minuterie soit détruite. La nouvelle minuterie est initialement désarmée.

       Le  paramètre  clockid indique l'horloge que la nouvelle minuterie utilise pour mesurer le
       temps. Il peut prendre une des valeurs suivantes :

       CLOCK_REALTIME
              Une horloge temps réel configurable à l'échelle du système.

       CLOCK_MONOTONIC
              Une horloge non configurable, toujours croissante qui mesure  le  temps  depuis  un
              instant  non  spécifié  dans  le  passé  et qui ne change pas après le démarrage du
              système.

       CLOCK_PROCESS_CPUTIME_ID (depuis Linux 2.6.12)
              Une horloge qui mesure le temps  CPU  (utilisateur  et  système)  consommé  par  le
              processus appelant (et tous ses threads).

       CLOCK_THREAD_CPUTIME_ID (depuis Linux 2.6.12)
              Une  horloge  qui  mesure  le  temps  CPU  (utilisateur et système) consommé par le
              processus appelant.

       CLOCK_BOOTTIME (Since Linux 2.6.39)
              Like CLOCK_MONOTONIC, this is a monotonically increasing  clock.  However,  whereas
              the  CLOCK_MONOTONIC  clock  does not measure the time while a system is suspended,
              the CLOCK_BOOTTIME  clock  does  include  the  time  during  which  the  system  is
              suspended.  This  is  useful  for  applications  that  need  to  be  suspend-aware.
              CLOCK_REALTIME is not suitable for such applications, since that clock is  affected
              by discontinuous changes to the system clock.

       CLOCK_REALTIME_ALARM (since Linux 3.0)
              This clock is like CLOCK_REALTIME, but will wake the system if it is suspended. The
              caller must have the CAP_WAKE_ALARM capability in order to set a timer against this
              clock.

       CLOCK_BOOTTIME_ALARM (since Linux 3.0)
              This clock is like CLOCK_BOOTTIME, but will wake the system if it is suspended. The
              caller must have the CAP_WAKE_ALARM capability in order to set a timer against this
              clock.

       CLOCK_TAI (since Linux 3.10)
              A system-wide clock derived from wall-clock time but ignoring leap seconds.

       See clock_getres(2)  for some further details on the above clocks.

       Comme  pour  les valeurs ci-dessus, clockid peut être l'identifiant clockid renvoyé par un
       appel à clock_getcpuclockid(3) ou pthread_getcpuclockid(3).

       Le paramètre sevp pointe vers  une  structure  sigevent  qui  indique  comment  l'appelant
       devrait être notifié quand la minuterie expire. Pour la définition et des détails généraux
       sur cette structure, consultez sigevent(7).

       Le champ sevp.sigev_notify peut avoir les valeurs suivantes :

       SIGEV_NONE
              Ne pas notifier de façon asynchrone quand la minuterie expire. La progression de la
              minuterie peut être observée en utilisant timer_gettime(2).

       SIGEV_SIGNAL
              Lors  de  l'expiration  de  la  minuterie,  produire  le signal sigev_signo pour le
              processus. Consultez sigevent(7) pour des détails généraux. Le champ si_code de  la
              structure  siginfo_t  sera mis à SI_TIMER. À tout moment, au plus un signal est mis
              en   attente   pour   le   processus   pour   une   horloge   donnée ;    consultez
              timer_getoverrun(2) pour plus de détails.

       SIGEV_THREAD
              Lors  de  l'expiration de la minuterie, appeler sigev_notify_function comme si elle
              était la fonction de démarrage d'un nouveau thread. Consultez sigevent(7) pour plus
              de détails.

       SIGEV_THREAD_ID (spécifique à Linux)
              Comme  SIGEV_SIGNAL,  mais  le  signal  est envoyé au thread dont l'identifiant est
              fourni dans sigev_notify_thread_id, qui doit être un thread du même  processus  que
              le  thread  appelant.  Le  champ  sigev_notify_thread_id  indique un identifiant de
              thread noyau, c'est-à-dire la valeur renvoyée par clone(2) ou gettid(2). Ce drapeau
              n'est destiné à être utilisé que par la bibliothèque des threads.

       Une valeur NULL pour sevp équivaut à indiquer un pointeur vers une structure sigevent dans
       laquelle sigev_notify vaut SIGEV_SIGNAL, sigev_signo vaut SIGALRM et sigev_value.sival_int
       vaut l'identifiant de l'horloge.

VALEUR RENVOYÉE

       S'il  réussit,  timer_create()  renvoie zéro et l'identifiant de la nouvelle minuterie est
       placé dans *timerid. En cas d'erreur, il renvoie -1 et errno contient le code d'erreur.

ERREURS

       EAGAIN Erreur temporaire lors de l'allocation de la  structure  de  la  minuterie  par  le
              noyau.

       EINVAL L'identifiant  d'horloge, sigev_notify, sigev_signo ou sigev_notify_thread_id n'est
              pas valable.

       ENOMEM Impossible d'allouer de la mémoire.

       ENOTSUP
              The kernel does not support creating a timer against this clockid.

       EPERM  clockid was CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM but  the  caller  did  not
              have the CAP_WAKE_ALARM capability.

VERSIONS

       Cet appel système est disponible depuis Linux 2.6.

CONFORMITÉ

       POSIX.1-2001, POSIX.1-2008.

NOTES

       Un programme peut créer plusieurs minuterie en utilisant timer_create().

       Les minuteries ne sont pas héritées par ses enfants lors d'un fork(2) et sont désarmées et
       détruites lors d'un appel système execve(2).

       Le noyau alloue par avance un « signal temps réel en attente » pour chaque minuterie créée
       par  timer_create().  De  ce  fait,  le  nombre  de minuteries est limité par la limite de
       ressources RLIMIT_SIGPENDING (voir setrlimit(2)).

       Les  minuteries  créée   par   timer_create()   sont   communément   appelées   « horloges
       (d'intervalle)   POSIX ».  L'API  des  minuteries  POSIX  est  constituée  des  interfaces
       suivantes :

       –  timer_create() : Créer une minuterie.

       –  timer_settime(2) : Armer (démarrer) ou désarmer (stopper) une minuterie.

       –  timer_gettime(2) : Récupérer le  temps  restant  jusqu'à  l'expiration  suivante  d'une
          minuterie, en plus de l'intervalle de la minuterie.

       –  timer_getoverrun(2) :  Renvoyer le décompte de dépassements pour la dernière expiration
          de la minuterie.

       –  timer_delete(2) : Désarmer et détruire une minuterie.

       Depuis Linux 3.10, le  fichier  /proc/[pid]/timers  peut  être  utilisé  pour  lister  les
       minuteries POSIX du processus de PID pid. Consultez proc(5) pour plus de détails.

       Since  Linux  4.10,  support  for POSIX timers is a configurable option that is enabled by
       default. Kernel support can be disabled via the CONFIG_POSIX_TIMERS option.

   différences entre bibliothèque C et noyau
       Une partie de  l'implémentation  des  minuteries  POSIX  est  fournie  par  la  glibc.  En
       particulier :

       –  Much of the functionality for SIGEV_THREAD is implemented within glibc, rather than the
          kernel. (This is necessarily so, since the thread involved in handling the notification
          is  one  that  must be managed by the C library POSIX threads implementation.) Although
          the notification delivered to  the  process  is  via  a  thread,  internally  the  NPTL
          implementation  uses  a  sigev_notify  value  of SIGEV_THREAD_ID along with a real-time
          signal that is reserved by the implementation (see nptl(7)).

       –  The implementation of the default case where evp is NULL is handled inside glibc, which
          invokes the underlying system call with a suitably populated sigevent structure.

       –  Les  identifiants  de  minuteries  fournis  au niveau utilisateur sont maintenus par la
          glibc, qui fait la correspondance avec les identifiants utilisés par le noyau.

       The POSIX timers system calls first appeared in Linux 2.6. Prior to this,  glibc  provided
       an  incomplete user-space implementation (CLOCK_REALTIME timers only) using POSIX threads,
       and in glibc versions before 2.17, the implementation falls  back  to  this  technique  on
       systems running pre-2.6 Linux kernels.

EXEMPLES

       Le  programme ci-dessous reçoit deux paramètres : une durée de sommeil, en seconde, et une
       fréquence de minuterie en nanosecondes. Le  programme  établit  un  gestionnaire  pour  le
       signal  qu'il  utilise  avec  la  minuterie,  puis  il  bloque le signal, crée et arme une
       minuterie qui expire à la fréquence donnée, s'endort pendant la durée  indiquée  et  enfin
       débloque  le signal de la minuterie. En supposant que la minuterie ait expiré au moins une
       fois pendant le sommeil du  programme,  le  gestionnaire  de  signal  sera  appelé  et  le
       gestionnaire  de  signal  affiche  des  informations  concernant  la  notification  de  la
       minuterie. Le programme se termine après un appel au gestionnaire de signal.

       Dans l'exemple d'exécution qui suit, le programme s'endort pour une  seconde  après  avoir
       créé  une  minuterie  de  d'une fréquence de 100 nanosecondes. Le temps que le signal soit
       débloqué et fournit, il y a eu environ dix millions de dépassements.

           $ ./a.out 1 10
           Establishing handler for signal 34
           Blocking signal 34
           timer ID is 0x804c008
           Sleeping for 1 seconds
           Unblocking signal 34
           Caught signal 34
               sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008
               overrun count = 10004886

   Source du programme

       #include <stdint.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <stdio.h>
       #include <signal.h>
       #include <time.h>

       #define CLOCKID CLOCK_REALTIME
       #define SIG SIGRTMIN

       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                               } while (0)

       static void
       print_siginfo(siginfo_t *si)
       {
           timer_t *tidp;
           int or;

           tidp = si->si_value.sival_ptr;

           printf("    sival_ptr = %p; ", si->si_value.sival_ptr);
           printf("    *sival_ptr = %#jx\n", (uintmax_t) *tidp);

           or = timer_getoverrun(*tidp);
           if (or == -1)
               errExit("timer_getoverrun");
           else
               printf("    overrun count = %d\n", or);
       }

       static void
       handler(int sig, siginfo_t *si, void *uc)
       {
           /* Note: calling printf() from a signal handler is not safe
              (and should not be done in production programs), since
              printf() is not async-signal-safe; see signal-safety(7).
              Nevertheless, we use printf() here as a simple way of
              showing that the handler was called. */

           printf("Caught signal %d\n", sig);
           print_siginfo(si);
           signal(sig, SIG_IGN);
       }

       int
       main(int argc, char *argv[])
       {
           timer_t timerid;
           struct sigevent sev;
           struct itimerspec its;
           long long freq_nanosecs;
           sigset_t mask;
           struct sigaction sa;

           if (argc != 3) {
               fprintf(stderr, "Usage: %s <sleep-secs> <freq-nanosecs>\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           /* Establish handler for timer signal */

           printf("Establishing handler for signal %d\n", SIG);
           sa.sa_flags = SA_SIGINFO;
           sa.sa_sigaction = handler;
           sigemptyset(&sa.sa_mask);
           if (sigaction(SIG, &sa, NULL) == -1)
               errExit("sigaction");

           /* Block timer signal temporarily */

           printf("Blocking signal %d\n", SIG);
           sigemptyset(&mask);
           sigaddset(&mask, SIG);
           if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)
               errExit("sigprocmask");

           /* Create the timer */

           sev.sigev_notify = SIGEV_SIGNAL;
           sev.sigev_signo = SIG;
           sev.sigev_value.sival_ptr = &timerid;
           if (timer_create(CLOCKID, &sev, &timerid) == -1)
               errExit("timer_create");

           printf("timer ID is %#jx\n", (uintmax_t) timerid);

           /* Start the timer */

           freq_nanosecs = atoll(argv[2]);
           its.it_value.tv_sec = freq_nanosecs / 1000000000;
           its.it_value.tv_nsec = freq_nanosecs % 1000000000;
           its.it_interval.tv_sec = its.it_value.tv_sec;
           its.it_interval.tv_nsec = its.it_value.tv_nsec;

           if (timer_settime(timerid, 0, &its, NULL) == -1)
                errExit("timer_settime");

           /* Sleep for a while; meanwhile, the timer may expire
              multiple times */

           printf("Sleeping for %d seconds\n", atoi(argv[1]));
           sleep(atoi(argv[1]));

           /* Unlock the timer signal, so that timer notification
              can be delivered */

           printf("Unblocking signal %d\n", SIG);
           if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)
               errExit("sigprocmask");

           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       clock_gettime(2), setitimer(2), timer_delete(2), timer_getoverrun(2), timer_settime(2),
       timerfd_create(2), clock_getcpuclockid(3), pthread_getcpuclockid(3), pthreads(7),
       sigevent(7), signal(7), time(7)

COLOPHON

       Cette page fait partie de la publication 5.10 du projet man-pages Linux. Une description
       du projet et des instructions pour signaler des anomalies et la dernière version de cette
       page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

       La traduction française de cette page de manuel a été créée par Christophe Blaess
       <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
       Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
       Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
       luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
       Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Cédric Boutillier
       <cedric.boutillier@gmail.com> et Frédéric Hantrais <fhantrais@gmail.com>

       Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
       Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
       conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
       message à debian-l10n-french@lists.debian.org ⟨⟩.