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

NOM

       timer_create - Creer une minuterie POSIX pour un processus

SYNOPSIS

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

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

       Effectuez l'edition des liens avec l'option -lrt.

   Exigences  de  macros  de  test de fonctionnalites pour la glibc (consultez
   feature_test_macros(7)) :

       timer_create() : _POSIX_C_SOURCE >= 199309L

DESCRIPTION

       timer_create()  cree  une  nouvelle  minuterie  pour   une   processus.
       L'identifiant  de  cette  nouvelle minuterie est renvoye dans le tampon
       pointe par timerid, qui  doit  etre  un  pointeur  different  de  NULL.
       L'identifiant est unique pour le processus, jusqu'a ce que la minuterie
       soit detruite. La nouvelle minuterie est initialement desarmee.

       Le parametre  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 reel configurable a l'echelle du systeme.

       CLOCK_MONOTONIC
              Une horloge non configurable, toujours croissante qui mesure  le
              temps  depuis  un  instant  non specifie dans le passe et qui ne
              change pas apres le demarrage du systeme.

       CLOCK_PROCESS_CPUTIME_ID (depuis Linux 2.6.12)
              Une horloge qui mesure le temps  CPU  (utilisateur  et  systeme)
              consomme 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 systeme)
              consomme par le processus appelant.

       Comme pour les  valeurs  ci-dessus,  clockid  peut  etre  l'identifiant
       clockid    renvoye   par   un   appel   a   clock_getcpuclockid(3)   ou
       pthread_getcpuclockid(3).

       Le parametre evp pointe vers une structure sigevent qui indique comment
       l'appelant  devrait  etre  notifie  quand  la minuterie expire. Pour la
       definition et des  details  generaux  sur  cette  structure,  consultez
       sigevent(7).

       Le champ evp.sigev_notify peut avoir les valeurs suivantes :

       SIGEV_NONE
              Ne  pas  notifier de facon asynchrone quand la minuterie expire.
              La progression de la minuterie peut etre observee  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
              details  generaux.  Le  champ  si_code de la structure siginfo_t
              sera mis a SI_TIMER. A tout moment, au plus un signal est mis en
              attente  pour  le  processus pour une horloge donnee ; consultez
              timer_getoverrun(2) pour plus de details.

       SIGEV_THREAD
              Lors    de    l'expiration    de    la    minuterie,     appeler
              sigev_notify_function   comme  si  elle  etait  la  fonction  de
              demarrage d'un nouveau thread. Consultez sigevent(7)  pour  plus
              de details.

       SIGEV_THREAD_ID (specifique a Linux)
              Comme  SIGEV_SIGNAL,  mais  le  signal est envoye au thread dont
              l'identifiant est fourni dans sigev_notify_thread_id,  qui  doit
              etre  un  thread  du  meme  processus que le thread appelant. Le
              champ sigev_notify_thread_id indique un  identifiant  de  thread
              noyau,   c'est-a-dire   la   valeur  renvoyee  par  clone(2)  ou
              gettid(2). Ce drapeau n'est destine a etre utilise  que  par  la
              bibliotheque des threads.

       Une  valeur  NULL  pour  evp  equivaut  a 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'EE

       S'il reussit,  timer_create()  renvoie  zero  et  l'identifiant  de  la
       nouvelle minuterie est place 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 memoire.

VERSIONS

       Cet appel systeme est disponible depuis Linux 2.6.

CONFORMIT'E

       POSIX.1-2001

NOTES

       Un   programme   peut   creer   plusieurs   minuterie   en    utilisant
       timer_create().

       Les  minuteries  ne sont pas heritees par ses enfants lors d'un fork(2)
       et sont desarmees et detruites lors d'un appel systeme execve(2).

       Le noyau alloue par avance un << signal temps reel en  attente >>  pour
       chaque  minuterie  creee  par  timer_create(). De ce fait, le nombre de
       minuteries est limite par la  limite  de  ressources  RLIMIT_SIGPENDING
       (voir setrlimit(2)).

       Les  minuteries  creee  par  timer_create()  sont  communement appelees
       << horloges (d'intervalle) POSIX >>. L'API  des  minuteries  POSIX  est
       constituee des interfaces suivantes :

       *  timer_create() : Creer une minuterie.

       *  timer_settime(2) :   Armer  (demarrer)  ou  desarmer  (stopper)  une
          minuterie.

       *  timer_gettime(2) : Recuperer le temps restant  jusqu'a  l'expiration
          suivante d'une minuterie, en plus de l'intervalle de la minuterie.

       *  timer_getoverrun(2) :  Renvoyer  le decompte de depassements pour la
          derniere expiration de la minuterie.

       *  timer_delete(2) : Desarmer et detruire une minuterie.

       Une partie de l'implementation des minuteries POSIX est fournie par  la
       glibc. En particulier :

       *  La  fonctionnalite  de  SIGEV_THREAD  est implementee dans la glibc,
          plutot que par le noyau.

       *  Les identifiants de minuteries fournis au  niveau  utilisateur  sont
          maintenus  par  la  glibc,  qui  fait  la  correspondance  avec  les
          identifiants utilises par le noyau.

       Les appels systeme pour les  minuteries  POSIX  sont  apparus  dans  le
       noyaux  Linux 2.6.  Auparavant, la glibc fournissait une implementation
       incomplete  en  espace  utilisateur  (les   minuteries   CLOCK_REALTIME
       uniquement)  en  utilisant  les  threads  POSIX,  et  la glibc actuelle
       utilise toujours cette implementation sur les systemes ayant  un  noyau
       anterieur au noyau Linux 2.6.

EXEMPLE

       Le  programme ci-dessous recoit deux parametres : une duree de sommeil,
       en seconde, et une frequence de minuterie en nanosecondes. Le programme
       etablit un gestionnaire pour le signal qu'il utilise avec la minuterie,
       puis il bloque le signal, cree et arme une minuterie qui  expire  a  la
       frequence  donnee, s'endort pendant la duree indiquee et enfin debloque
       le signal de la minuterie. En supposant que la minuterie ait expire  au
       moins  une  fois  pendant  le  sommeil du programme, le gestionnaire de
       signal  sera  appele  et  le  gestionnaire  de   signal   affiche   des
       informations  concernant  la notification de la minuterie. Le programme
       se termine apres un appel au gestionnaire de signal.

       Dans l'exemple d'execution qui suit, le  programme  s'endort  pour  une
       seconde  apres  avoir  cree  une  minuterie  de  d'une frequence de 100
       nanosecondes. Le temps que le signal soit debloque et fournit, il  y  a
       eu environ dix millions de depassements.

           $ ./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 <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 = 0x%lx\n", (long) *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
              strictly correct, since printf() is not async-signal-safe;
              see signal(7) */

           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 0x%lx\n", (long) 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_settime(2),
       timer_getoverrun(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 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/>.

       Nicolas   Francois   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> >>.