Provided by: manpages-fr-dev_4.18.1-1_all bug

NOM

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

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc), depuis la glibc 2.17

       Avant la glibc 2.17, bibliothèque de temps réel (librt, -lrt)

SYNOPSIS

       #include <time.h>

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

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

   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(3).

       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.  Si
       elles échouent, -1 est renvoyé et errno est positionné pour indiquer l'erreur.

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(), clock_settime()        │ Sécurité des threads │ MT-Safe │
       └────────────────────────────────────────────────────────┴──────────────────────┴─────────┘

STANDARDS

       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 <stdbool.h>
       #include <stdint.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <time.h>

       #define SECS_IN_DAY (24 * 60 * 60)

       static void
       displayClock(clockid_t clock, const char *name, bool showRes)
       {
           long             days;
           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);

           days = ts.tv_sec / SECS_IN_DAY;
           if (days > 0)
               printf("%ld jours + ", 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("     résolution : %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),   timespec(3),   time(7),
       time_namespaces(7), vdso(7), hwclock(8)

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