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

NOM

       adjtimex, clock_adjtime, ntp_adjtime - Régler l'horloge du noyau (kernel clock)

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <sys/timex.h>

       int adjtimex(struct timex *buf);

       int clock_adjtime(clockid_t clk_id, struct timex *buf);

       int ntp_adjtime(struct timex *buf);

DESCRIPTION

       Linux  utilise  l'algorithme  d'ajustement d'horloge de David L. Mills (voir la RFC 5905).
       L'appel système adjtimex() lit et écrit éventuellement les  paramètres  d'ajustement  pour
       cet  algorithme.  Il  utilise  un  pointeur sur une structure timex pour mettre à jour les
       paramètres du noyau avec les valeurs  des  champs  (sélectionnés),  et  renvoyer  la  même
       structure avec les valeurs actuelles du noyau. La structure est déclarée comme suit :

           struct timex {
               int  modes;      /* choix du mode */
               long offset;     /* décalage temporel ; nanosecondes, si drapeau
                                   STA_NANO est défini, sinon
                                   microseconde*/
               long freq;       /* décalage de fréquence ; unités, voir NOTES */
               long maxerror;   /* erreur maximale (microseconde) */
               long esterror;   /* erreur estimée (microseconde) */
               int  status;     /* commande horloge/état */
               long constant;   /* constante de temps PLL */
               long precision;  /* précision de l’horloge
                                   (microseconde, lecture seule) */
               long tolerance;  /* tolérance fréquence horloge (lecture seule);
                                   unités, voir NOTES */
               struct timeval time;
                                /* heure actuelle (lecture seule, sauf pour
                                   ADJ_SETOFFSET) ; sur renvoi, time.tv_usec
                                   contient nanosecondes, si le drapeau
                                   STA_NANO défini, sinon microsecondes */
               long tick;       /* microsecondes entre tics horloge */
               long ppsfreq;    /* fréquence PPS (pulse per second)
                                   (lecture seule) ; unités, voir NOTES */
               long jitter;     /* jitter PPS (lecture seule) ; nanosecondes, si
                                   drapeau état STA_NANO défini, sinon
                                   microsecondes */
               int  shift;      /* durée intervalle PPS
                                   (secondes, lecture seule) */
               long stabil;     /* stabilité PPS (lecture seule);
                                   unités, voir NOTES */
               long jitcnt;     /* nombre PPS dépassements limite de jitter
                                   évènements (lecture seule)
               long calcnt;     /* nombre PPS d’intervalles de calibration
                                   (lecture seule) */
               long errcnt;     /* nombre PPS d’erreurs de calibration
                                   (lecture seule) */
               long stbcnt;     /* nombre PPS dépassements limite stabilité
                                   évènements (lecture seule)
               int tai;         /* décalage TAI, comme défini par l’opération
                                   ADJ_TAI (secondes, lecture seule,
                                   depuis Linux 2.6.26) */
               /* octets de remplissage supplémentaires pour une extension future*/
           };

       Le  champ  modes  détermine les paramètres éventuels à écrire (comme décrit plus loin dans
       cette  page,  les  constantes  pour  ntp_adjtime()  sont  équivalentes  mais  ont  un  nom
       différent).  Il s'agit d'un masque binaire contenant une combinaison or bit à bit de zéros
       ou plusieurs des bits suivants :

       ADJ_OFFSET
              Définir la position de l'heure à partir de  buf.offset.  Depuis  Linux  2.6.26,  la
              valeur  fournie  figure  sur  la  plage (-0.5s, +0.5s). Sur les anciens noyaux, une
              erreur EINVAL survient si la valeur fournie sort de cette plage.

       ADJ_FREQUENCY
              Définir la position de la fréquence à partir de buf.freq. Depuis Linux  2.6.26,  la
              valeur  fournie figure sur la plage (-32768000, +32768000). Sur les anciens noyaux,
              une erreur EINVAL survient si la valeur fournie sort de cette plage.

       ADJ_MAXERROR
              Définir l'erreur de temps maximale à partir de buf.maxerror.

       ADJ_ESTERROR
              Définir l'erreur de temps estimée à partir de buf.esterror.

       ADJ_STATUS
              Définir les bits de l'état de l'horloge à partir de buf.status. Une description  de
              ces bits est disponible ci-dessous.

       ADJ_TIMECONST
              Définir  la constante PLL de l'heure à partir de buf.constant. Si le drapeau d'état
              STA_NANO (voir ci-dessous) est vide, le noyau ajoute 4 à cette valeur.

       ADJ_SETOFFSET (depuis Linux 2.6.39)
              Ajouter buf.time à l'heure actuelle. Si  buf.status  inclut  le  drapeau  ADJ_NANO,
              buf.time.tv_usec  est  interprété  comme  une  valeur en nanoseconde ; sinon il est
              interprété en microseconde.

              La  valeur  de  buf.time  est  la  somme  de  ses  deux  champs,  mais   le   champ
              buf.time.tv_usec doit toujours être positif. L'exemple suivant montre la manière de
              normaliser une timeval avec une résolution en nanoseconde.

                  while (buf.time.tv_usec < 0) {
                      buf.time.tv_sec  -= 1;
                      buf.time.tv_usec += 1000000000;
                  }

       ADJ_MICRO (depuis Linux 2.6.26)
              Sélectionner la résolution en microseconde.

       ADJ_NANO (depuis Linux 2.6.26)
              Sélectionner la résolution en nanoseconde. Vous ne devriez spécifier que  ADJ_MICRO
              ou ADJ_NANO.

       ADJ_TAI (depuis Linux 2.6.26)
              Définir la position du TAI (temps atomique international) à partir de buf.constant.

              ADJ_TAI  ne  devrait  pas  être utilisé avec ADJ_TIMECONST, puisque le dernier mode
              utilise également le champ buf.constant.

              Pour une explication complète du  temps  atomique  international  (TAI)  et  de  la
              différence   entre   ce  temps  et  celui  universel  coordonné  (UTC),  voir  BIPMhttp://www.bipm.org/en/bipm/tai/tai.htmlADJ_TICK
              Définir la valeur d'un tic à partir de buf.tick.

       Autrement, modes peut être indiqué sous la forme de valeurs suivantes  (masque  multibit),
       auquel cas aucun autre bit ne devrait être spécifié dans modes :

       ADJ_OFFSET_SINGLESHOT
              adjtime(3)   à  l'ancienne :  ajuster  (graduellement)  l'heure  avec  des  valeurs
              spécifiées dans buf.offset, ce qui indique un ajustement en microseconde.

       ADJ_OFFSET_SS_READ (fonctionnel depuis Linux 2.6.28)
              Renvoyer (dans  buf.offset)  le  temps  restant  à  ajuster  après  une  précédente
              opération  ADJ_OFFSET_SINGLESHOT.  Cette  fonctionnalité  a  été ajoutée dans Linux
              2.6.24, mais elle ne fonctionnait pas correctement jusqu'à Linux 2.6.28.

       Les utilisateurs normaux sont limités à une valeur de modes nulle  ou  ADJ_OFFSET_SS_READ.
       Seul le superutilisateur peut écrire n'importe quel paramètre.

       Le  champ  buf.status  est un masque de bits utilisé pour définir et/ou récupérer les bits
       d'état associés  à  l'implémentation  NTP.  Certains  bits  du  masque  sont  lisibles  et
       modifiables, alors que d'autres ne sont qu'en lecture seule.

       STA_PLL (lecture-écriture)
              Activer les mises à jour « phase-locked loop » (PLL) à l’aide de ADJ_OFFSET.

       STA_PPSFREQ (lecture-écriture)
              Activer le mode de fréquence PPS (pulse-per-second ou battement par seconde).

       STA_PPSTIME (lecture-écriture)
              Activer le mode temporel PPS.

       STA_FLL (lecture-écriture)
              Sélectionner le mode « frequency-locked loop » (FLL).

       STA_INS (lecture-écriture)
              Insérer  un  saut d’une seconde après la dernière seconde de la journée UTC, ce qui
              étend ainsi la dernière minute de la journée d'une seconde.  L'insertion  d'un  tel
              saut s'effectuera chaque jour tant que ce drapeau est positionné.

       STA_DEL (lecture-écriture)
              Supprimer  le saut d’une seconde à la dernière seconde de la journée UTC. Une telle
              suppression se produira chaque jour tant que ce drapeau est positionné.

       STA_UNSYNC (lecture-écriture)
              Horloge non synchronisée.

       STA_FREQHOLD (lecture-écriture)
              Conserver la fréquence. Normalement, il  résulte  des  ajustements  effectués  avec
              ADJ_OFFSET  des  ajustements  de  fréquence  amortis. Un seul appel corrige donc la
              position actuelle, mais comme les compensations dans le même sens se répètent,  les
              petits  ajustements  de  fréquence  s'accumuleront pour corriger le décalage à long
              terme.

              Ce drapeau empêche les petits ajustements de fréquence lors de la correction  d'une
              valeur ADJ_OFFSET.

       STA_PPSSIGNAL (lecture seule)
              Un signal PPS (pulse-per-second, ou battement par seconde) valable est présent.

       STA_PPSJITTER (lecture seule)
              Fluctuation de signal (jitter) PPS excessive.

       STA_PPSWANDER (lecture seule)
              Dérive de signal (wander) PPS excessive.

       STA_PPSERROR (lecture seule)
              Erreur de calibrage du signal PPS.

       STA_CLOCKERR (lecture seule)
              Erreur d'horloge matérielle.

       STA_NANO (lecture seule ; depuis Linux 2.6.26)
              Résolution  (0 = microseconde,  1 = nanoseconde).  Positionné à l’aide de ADJ_NANO,
              annulé à l’aide de ADJ_MICRO.

       STA_MODE (depuis Linux 2.6.26)
              Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).

       STA_CLK (en lecture seule ; depuis Linux 2.6.26)
              Source de l'horloge (0 = A, 1 = B) ; actuellement inusité.

       Les tentatives de positionner des bits d'état qui sont  en  lecture  seule  sont  ignorées
       silencieusement.

   clock_adjtime ()
       L'appel  système clock_adjtime() (ajouté à Linux 2.6.39) se comporte comme adjtimex() mais
       il prend un paramètre clk_id supplémentaire pour indiquer sur  quelle  horloge  spécifique
       agir.

   ntp_adjtime ()
       La  fonction  de  bibliothèque ntp_adjtime() (décrite dans le « Kernel Application Program
       API », KAPI) est une interface plus portable pour effectuer la même tâche que  adjtimex().
       À part les points suivants, elle est identique à adjtimex() :

       •  Les  constantes utilisées dans les modes sont préfixées de « MOD_ » au lieu de « ADJ_ »
          et elles ont les mêmes suffixes (MOD_OFFSET, MOD_FREQUENCY, et ainsi  de  suite),  sauf
          les exceptions indiquées dans les points suivants.

       •  MOD_CLKA est le synonyme de ADJ_OFFSET_SINGLESHOT.

       •  MOD_CLKB est le synonyme de ADJ_TICK.

       •  Il n’existe pas de synonyme pour ADJ_OFFSET_SS_READ, non décrit dans la KAPI.

VALEUR RENVOYÉE

       S'ils   réussissent,   adjtimex()   et   ntp_adjtime()  renvoient  l'état  de  l'horloge ;
       c'est-à-dire une des valeurs suivantes :

       TIME_OK     Horloge synchronisée, aucun ajustement de saut de seconde en attente.

       TIME_INS    Indication qu'un saut de seconde sera ajouté à la fin de la journée UTC.

       TIME_DEL    Indication que le saut de seconde sera retiré en fin de journée UTC.

       TIME_OOP    L'insertion d'un saut de seconde est en cours.

       TIME_WAIT   L'insertion ou la suppression d'un saut  de  seconde  a  été  terminée.  Cette
                   valeur  sera renvoyée jusqu'à ce qu'une prochaine opération ADJ_STATUS ne vide
                   les drapeaux STA_INS et STA_DEL.

       TIME_ERROR  L'horloge système n'est pas synchronisée avec un serveur fiable. Cette  valeur
                   est renvoyée si un des éléments suivants reste vrai :

                   •  STA_UNSYNC ou STA_CLOCKERR est défini.

                   •  STA_PPSSIGNAL   est   vide   et  soit  STA_PPSFREQ,  soit  STA_PPSTIME  est
                      positionné.

                   •  STA_PPSTIME STA_PPSJITTER sont tous deux définis.

                   •  STA_PPSFREQ est  défini  et  soit  STA_PPSWANDER,  soit  STA_PPSJITTER  est
                      défini.

                   Le nom symbolique TIME_BAD est synonyme de TIME_ERROR, fourni pour des raisons
                   de rétrocompatibilité.

       Remarquez qu'à partir de Linux 3.4, l'appel  agit  de  manière  asynchrone  et  la  valeur
       renvoyée ne reflètera en général pas un changement d'état provoqué par l'appel lui-même.

       En cas d'échec, ces appels renvoient -1 et définissent errno pour indiquer l'erreur.

ERREURS

       EFAULT buf pointe en dehors de l'espace d'adressage accessible en écriture.

       EINVAL (avant Linux 2.6.26)
              Vous  avez  essayé  de  positionner  buf.freq  sur  une  valeur au-delà de la plage
              (-33554432, +33554432).

       EINVAL (avant Linux 2.6.26)
              Vous avez essayé de positionner buf.offset sur  une  valeur  au-delà  de  la  plage
              autorisée.  Avant  Linux  2.0,  la plage autorisée était (-131072, +131072). Depuis
              Linux 2.0, la plage autorisée est (-512000, +512000).

       EINVAL Vous avez essayé de positionner buf.status sur  une  valeur  différente  de  celles
              indiquées ci-dessus.

       EINVAL Le  clk_id  donné à clock_adjtime() n'est pas valable pour une de ces deux raisons.
              Soit la valeur positive de l'ID de l'horloge codée en dur à la manière de  System-V
              dépasse  l'intervalle,  soit  le clk_id dynamique ne se rapporte pas à une instance
              valable d'une horloge.  Voir  clock_gettime(2)  pour  un  point  sur  les  horloges
              dynamiques.

       EINVAL Une tentative a été faite de définir buf.tick en dehors de l'intervalle 900000/HZ à
              1100000/HZ, où HZ est la fréquence d'interruption de l’ordonnanceur du système.

       ENODEV Le périphérique qu'on peut brancher à chaud (comme en USB par  exemple)  représenté
              par  un  clk_id  dynamique  a disparu après avoir été ouvert. Voir clock_gettime(2)
              pour un point sur les horloges dynamiques.

       EOPNOTSUPP
              Le clk_id fourni ne prend pas en charge l'ajustement.

       EPERM  buf.modes n'est ni nul ni ADJ_OFFSET_SS_READ, et l'appelant n'a pas suffisamment de
              privilèges. Sous Linux, la capacité CAP_SYS_TIME est nécessaire.

ATTRIBUTS

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

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

STANDARDS

       Aucune de ces interfaces n'est décrite par POSIX.1

       adjtimex() et clock_adjtime() sont spécifiques à Linux et ils ne doivent pas être employés
       dans des programmes destinés à être portés sur d'autres systèmes.

       L'API préférée pour le démon NTP est ntp_adjtime().

NOTES

       Dans une structure timex, freq, ppsfreq et stabil sont des ppm (parts  per  million)  avec
       une  partie décimale de 16 bits, ce qui veut dire qu'une valeur de 1 dans un de ces champs
       veut dire en fait 2^-16 ppm et 2^16=65536 vaut 1 ppm. Cela vaut tant pour les  valeurs  en
       entrée (dans le cas de freq) que celles en sortie.

       Le traitement du saut de seconde effectué par STA_INS et STA_DEL se fait par le noyau dans
       le contexte de l’ordonnanceur. Ainsi, il prendra un tic de  la  seconde  pour  insérer  ou
       supprimer un saut de seconde.

VOIR AUSSI

       clock_gettime(2),    clock_settime(2),    settimeofday(2),   adjtime(3),   ntp_gettime(3),
       capabilities(7), time(7), adjtimex(8), hwclock(8)

       NTP "Kernel Application Program Interface" ⟨http://www.slac.stanford.edu/comp/unix/
       package/rtems/src/ssrlApps/ntpNanoclock/api.htm⟩

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