jammy (2) clock_gettime.2.gz

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

NOM

       clock_getres, clock_gettime, clock_settime - Fonctions d'horloge et de temps

SYNOPSIS

       #include <time.h>

       int clock_getres(clockid_t clockid, struct timespec *res);

       int clock_gettime(clockid_t clockid, struct timespec *tp);

       int clock_settime(clockid_t clockid, const struct timespec *tp);

       Lier avec -lrt (seulement pour les versions de la glibc antérieures à 2.17).

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

       clock_getres(), clock_gettime(), clock_settime() :
              _POSIX_C_SOURCE >= 199309L

DESCRIPTION

       La  fonction  clock_getres()  cherche  la  résolution  (précision)  de  l'horloge  clockid
       spécifiée et si res est non NULL, elle l'enregistre dans la structure timespec pointée par
       res. La résolution des horloges dépend de l'implémentation et ne peut pas être  configurée
       par  un  processus  particulier.  Si  la  valeur  du  temps  pointé  par  l'argument tp de
       clock_settime() n'est pas un multiple de res, cette valeur est tronquée à un  multiple  de
       res.

       Les  fonctions  clock_gettime()  et  clock_settime() récupèrent et configurent le temps de
       l'horloge clockid spécifiée.

       Les arguments res et tp sont des structures timespec définies dans <time.h> :

           struct timespec {
               time_t   tv_sec;        /* secondes */
               long     tv_nsec;       /* nanosecondes */
           };

       L'argument clockid est l'identifiant d'une horloge particulière  sur  laquelle  agir.  Une
       horloge  peut être globale au système, et par conséquent visible de tous les processus, ou
       propre à un processus, si elle mesure le temps uniquement pour celui-ci.

       Toutes les implémentations prennent en charge l'horloge temps réel globale,  laquelle  est
       identifiée  par CLOCK_REALTIME. Son temps représente le nombre de secondes et nanosecondes
       écoulées depuis l'époque UNIX (1er janvier 1970 à 00:00:00 UTC).  Lorsque  son  temps  est
       modifié,  les  horloges  mesurant  un  intervalle de temps ne sont pas affectées alors que
       celles indiquant une date (heure) absolue le sont.

       Plusieurs horloges peuvent  être  implémentées.  L'interprétation  des  valeurs  de  temps
       correspondantes et l'effet sur les temporisateurs ne sont pas spécifiés.

       Les  versions  suffisamment  récentes  de  la  glibc et du noyau Linux gèrent les horloges
       suivantes :

       CLOCK_REALTIME
              Horloge système réglable qui mesure le temps réel (c'est-à-dire comme une pendule).
              Modifier  cette  horloge  nécessite  des  privilèges  adéquats.  Cette  horloge est
              concernée  par  les  sauts  discontinus  de  l'heure  système   (par   exemple   si
              l'administrateur  modifie  l'heure  lui-même),  et par les ajustements incrémentaux
              effectués par adjtime(3) et NTP.

       CLOCK_REALTIME_ALARM (depuis Linux 3.0 ; spécifique à Linux)
              Comme CLOCK_REALTIME, mais non réglable. Voir timer_create(2) pour plus de détails.

       CLOCK_REALTIME_COARSE (depuis Linux 2.6.32 ; spécifique à Linux)
              Horloge plus rapide mais moins précise que CLOCK_REALTIME. Cette horloge n'est  pas
              réglable.  À  utiliser  pour  obtenir  rapidement des données d'horodatage avec une
              résolution  grossière.  Elle  exige  une  prise  en  charge  spécifique  à   chaque
              architecture  et  probablement  d'être  prise  en  charge par une architecture dans
              vdso(7).

       CLOCK_TAI (depuis Linux 3.10 ; spécifique à Linux)
              Horloge système non réglable dérivée d’une pendule mais ignorant le  franchissement
              de secondes. Cette horloge ne connaît ni discontinuités ni sauts en arrière suite à
              des insertions NTP de franchissement de secondes, contrairement à CLOCK_REALTIME.

              L'acronyme  TAI  renvoie  à  « International  Atomic  Time »  (temps  international
              atomique).

       CLOCK_MONOTONIC
              Horloge  système  non  réglable  qui  représente  le  temps monotone depuis — selon
              POSIX — « some unspecified point in the past » (un point indéfini  du  passé).  Sur
              Linux,  ce  point  correspond  au  nombre  de  secondes  passées  depuis le dernier
              démarrage du système.

              L'horloge CLOCK_MONOTONIC n'est pas concernée par les sauts discontinus de  l'heure
              système  (par  exemple  si  l'administrateur  modifie  l'heure  lui-même), mais est
              affectée par les ajustements incrémentaux effectués par adjtime(3)  et  NTP.  Cette
              horloge  ne  compte pas le temps durant lequel le système est en veille. Toutes les
              variantes de CLOCK_MONOTONIC garantissent que  le  temps  renvoyé  par  des  appels
              consécutifs  ne créeront pas de retour en arrière, tandis que les appels successifs
              — selon  l'architecture —  renvoient  des  valeurs  temporelles  identiques   (sans
              augmentation).

       CLOCK_MONOTONIC_COARSE (depuis Linux 2.6.32 ; spécifique à Linux)
              Horloge plus rapide mais moins précise que CLOCK_MONOTONIC. À utiliser pour obtenir
              rapidement des données d'horodatage avec une résolution grossière. Elle  exige  une
              prise  en  charge  spécifique à chaque architecture et probablement d'être prise en
              charge par une architecture dans vdso(7).

       CLOCK_MONOTONIC_RAW (depuis Linux 2.6.28 ; spécifique à Linux)
              Similaire à CLOCK_MONOTONIC, mais fournit un accès direct à un temps  matériel  qui
              n'est  pas  sujet  ni aux ajustements NTP ni aux ajustements incrémentaux effectués
              par adjtime(3). Cette horloge ne compte pas le temps durant lequel le  système  est
              en veille.

       CLOCK_BOOTTIME (depuis Linux 2.6.39 ; spécifique à Linux)
              Horloge  système non réglable identique à CLOCK_MONOTONIC, mais qui prend également
              en compte le temps écoulé pendant la veille du système. Cela offre aux applications
              une  horloge  monotone  tenant  compte  des  veilles,  sans  avoir  à s'occuper des
              problèmes de discontinuités de CLOCK_REALTIME si l'horloge est  mise  à  jour  avec
              settimeofday(2) ou équivalent.

       CLOCK_BOOTTIME_ALARM (depuis Linux 3.0 ; spécifique à Linux)
              Comme CLOCK_BOOTTIME. Voir timer_create(2) pour plus de détails.

       CLOCK_PROCESS_CPUTIME_ID (depuis Linux 2.6.12)
              Il s'agit d'une horloge qui mesure le temps de processeur consommé par ce processus
              (à savoir le temps de processeur consommé par tous les threads du  processus).  Sur
              Linux, cette horloge n'est pas réglable.

       CLOCK_THREAD_CPUTIME_ID (depuis Linux 2.6.12)
              Il  s'agit  d'une horloge qui mesure le temps de processeur consommé par ce thread.
              Sur Linux, cette horloge n'est pas réglable.

       Linux implémente aussi des instances d'horloge dynamique comme décrit ci-dessous.

   Horloges dynamiques
       Outre les ID d'horloge à la manière System-V codés en dur décrits ci-dessus,  Linux  prend
       également en charge des opérations d'horloge POSIX sur certains fichiers de périphériques.
       De tels périphériques s'appellent des « horloges dynamiques » et  ils  sont  gérés  depuis
       Linux 2.6.39.

       Avec les macros adéquates, les descripteurs de fichier ouvert peuvent être convertis en ID
       d'horloge et passés à  clock_gettime(),  clock_settime()  et  clock_adjtime(2).  L'exemple
       suivant  montre  la  manière  de  convertir  un  descripteur  de  fichier  en ID d'horloge
       dynamique.

           #define CLOCKFD 3
           #define FD_TO_CLOCKID(fd)   ((~(clockid_t) (fd) << 3) | CLOCKFD)
           #define CLOCKID_TO_FD(clk)  ((unsigned int) ~((clk) >> 3))

           struct timespec ts;
           clockid_t clkid;
           int fd;

           fd = open("/dev/ptp0", O_RDWR);
           clkid = FD_TO_CLOCKID(fd);
           clock_gettime(clkid, &ts);

VALEUR RENVOYÉE

       clock_gettime(), clock_settime() et clock_getres() renvoient 0 si elles réussissent ou  -1
       si elles échouent, auquel cas errno est positionné en fonction.

ERREURS

       EACCES clock_settime()  n'a  pas  les  droits  d'écriture  sur  l'horloge  POSIX dynamique
              spécifiée.

       EFAULT tp pointe en dehors de l'espace d'adressage accessible.

       EINVAL Le clockid indiqué n'est pas valable pour une ou plusieurs raisons. Soit la  valeur
              positive  codée en dur à la manière de System-V est en dehors de l'intervalle, soit
              l'ID de l'horloge dynamique ne renvoie pas à une instance valable d'horloge.

       EINVAL (clock_settime()) :  tp.tv_sec  est  négatif  ou  tp.tv_nsec   dépasse   la   plage
              [0..999 999 999].

       EINVAL La clockid indiquée dans un appel à clock_settime() n'est pas une horloge réglable.

       EINVAL (depuis Linux 4.3)
              Un  appel  à  clock_settime()  avec  un  clockid  de  CLOCK_REALTIME  a  essayé  de
              positionner l'heure sur  une  valeur  inférieure  à  celle  actuelle  de  l'horloge
              CLOCK_MONOTONIC.

       ENODEV Le  périphérique  connectable  à  chaud  (comme  USB par exemple) représenté par un
              clk_id dynamique a disparu après que son fichier de périphérique a été ouvert.

       ENOTSUP
              L'opération n'est pas prise en charge par l'horloge POSIX dynamique indiquée.

       EPERM  clock_settime() n'a pas l'autorisation de configurer l'horloge spécifiée.

VERSIONS

       Ces appels système sont apparus dans Linux 2.6.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌─────────────────────────────────┬──────────────────────┬─────────┐
       │InterfaceAttributValeur  │
       ├─────────────────────────────────┼──────────────────────┼─────────┤
       │clock_getres(), clock_gettime(), │ Sécurité des threads │ MT-Safe │
       │clock_settime()                  │                      │         │
       └─────────────────────────────────┴──────────────────────┴─────────┘

CONFORMITÉ

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

       Sur  les  systèmes  conformes  à  la  spécification  POSIX sur lesquels ces fonctions sont
       disponibles, la constante symbolique _POSIX_TIMERS est définie dans <unistd.h> comme étant
       une   valeur   supérieure   à   0.   Les  constantes  symboliques  _POSIX_MONOTONIC_CLOCK,
       _POSIX_CPUTIME,      _POSIX_THREAD_CPUTIME      indiquent       que       CLOCK_MONOTONIC,
       CLOCK_PROCESS_CPUTIME_ID,   CLOCK_THREAD_CPUTIME_ID  sont  disponibles.  (Consultez  aussi
       sysconf(3).)

NOTES

       POSIX.1 spécifie ce qui suit :

              Configurer la valeur de l'horloge  CLOCK_REALTIME  avec  clock_settime(2)  ne  doit
              avoir d'effet ni sur les threads bloqués attendant un service de temps relatif basé
              sur cette horloge, y compris la fonction  nanosleep() ;  ni  sur  l'expiration  des
              compteurs  relatifs  basés sur cette horloge. En conséquence, ces services de temps
              doivent expirer lorsque la durée relative demandée est atteinte, indépendamment  de
              l'ancienne ou la nouvelle valeur de l'horloge.

       Selon  POSIX.1-2001,  un  processus  avec  des  « privilèges  adéquats »  peut changer les
       horloges CLOCK_PROCESS_CPUTIME_ID et CLOCK_THREAD_CPUTIME_ID  avec  clock_settime().  Sous
       Linux,  ces horloges ne peuvent pas être modifiées (c'est-à-dire qu'aucun processus n'a de
       « privilèges adéquats »).

   différences entre bibliothèque C et noyau
       Sur certaines architectures; une implémentation de clock_gettime()  est  fournie  dans  le
       vdso(7).

   Note historique pour les systèmes multiprocesseurs (SMP)
       Avant   la   prise   en   charge   par  le  noyau  Linux  de  CLOCK_PROCESS_CPUTIME_ID  et
       CLOCK_THREAD_CPUTIME_ID, la glibc a mis en œuvre ces horloges sur bien des plate-formes en
       utilisant  les  registres  temporisateurs  des CPU (TSC sur i386, AR.ITC sur Itanium). Les
       registres peuvent être différents entre les CPU avec pour conséquence des résultats bidons
       pour ces horloges si un processus a été transféré sur un autre CPU.

       Si les CPU d'un système multiprocesseur ont différentes sources d'horloges, il n'y a aucun
       moyen de maintenir une corrélation entre les registres temporisateurs puisque  chaque  CPU
       tournera  à  une  fréquence légèrement différente. Si c'est le cas, clock_getcpuclockid(0)
       renverra ENOENT pour signifier cette condition. Les deux horloges seront donc utiles si on
       peut être certain que le processus reste sur un CPU en particulier.

       Les  processeurs  d'un système multiprocesseur ne démarrent pas exactement au même moment,
       ainsi les registres temporisateurs sont lancés avec un décalage.  Certaines  architectures
       incluent  un  code  pour tenter de limiter ce décalage au démarrage. Toutefois, ce code ne
       garantit pas l'accord précis des décalages. La glibc  ne  contient  rien  pour  gérer  ces
       décalages  (à  la  différence  du  noyau Linux). Typiquement, ces décalages sont petits et
       ainsi, leurs effets peuvent être négligeables dans la plupart des cas.

       Depuis la glibc 2.4, les fonctions qui encapsulent les appels système décrits  dans  cette
       page  permettent  d'éviter  les  problèmes  mentionnés ci-dessus en utilisant les horloges
       CLOCK_PROCESS_CPUTIME_ID et  CLOCK_THREAD_CPUTIME_ID  du  noyau,  lorsque  celles-ci  sont
       disponibles (c'est-à-dire les versions de Linux 2.6.12 et ultérieures).

EXEMPLES

       Le  programme ci-dessous montre l'utilisation de clock_gettime() et de clock_getres() avec
       différentes horloges. Il s'agit d'un exemple de ce  qu'on  pourrait  voir  en  lançant  le
       programme :

           $ ./clock_times x
           CLOCK_REALTIME : 1585985459.446 (18356 days +  7h 30m 59s)
                resolution:          0.000000001
           CLOCK_TAI      : 1585985496.447 (18356 days +  7h 31m 36s)
                resolution:          0.000000001
           CLOCK_MONOTONIC:      52395.722 (14h 33m 15s)
                resolution:          0.000000001
           CLOCK_BOOTTIME :      72691.019 (20h 11m 31s)
                resolution:          0.000000001

   Source du programme

       /* clock_times.c

          Sous licence GNU General Public v2 ou postérieure.
       */
       #define _XOPEN_SOURCE 600
       #include <time.h>
       #include <stdint.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <stdbool.h>
       #include <unistd.h>

       #define SECS_IN_DAY (24 * 60 * 60)

       static void
       displayClock(clockid_t clock, const char *name, bool showRes)
       {
           struct timespec ts;

           if (clock_gettime(clock, &ts) == -1) {
               perror("clock_gettime");
               exit(EXIT_FAILURE);
           }

           printf("%-15s: %10jd.%03ld (", name,
                   (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);

           long days = ts.tv_sec / SECS_IN_DAY;
           if (days > 0)
               printf("%ld days + ", days);

           printf("%2dh %2dm %2ds",
                   (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
                   (int) (ts.tv_sec % 3600) / 60,
                   (int) ts.tv_sec % 60);
           printf(")\n");

           if (clock_getres(clock, &ts) == -1) {
               perror("clock_getres");
               exit(EXIT_FAILURE);
           }

           if (showRes)
               printf("     resolution: %10jd.%09ld\n",
                       (intmax_t) ts.tv_sec, ts.tv_nsec);
       }

       int
       main(int argc, char *argv[])
       {
           bool showRes = argc > 1;

           displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
       #ifdef CLOCK_TAI
           displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
       #endif
           displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
       #ifdef CLOCK_BOOTTIME
           displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
       #endif
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       date(1),  gettimeofday(2),  settimeofday(2),  time(2), adjtime(3), clock_getcpuclockid(3),
       ctime(3), ftime(3),  pthread_getcpuclockid(3),  sysconf(3),  time(7),  time_namespaces(7),
       vdso(7), hwclock(8)

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>  et  Jean-Philippe  MENGUAL
       <jpmengual@debian.org>

       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 ⟨⟩.

                                         21 décembre 2020                         CLOCK_GETRES(2)