adjtimex(2) System Calls Manual adjtimex(2) NOM adjtimex, clock_adjtime, ntp_adjtime - Regler l'horloge du noyau (kernel clock) BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include 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 systeme adjtimex() lit et ecrit eventuellement les parametres d'ajustement pour cet algorithme. Il utilise un pointeur sur une structure timex pour mettre a jour les parametres du noyau avec les valeurs des champs (selectionnes), et renvoyer la meme structure avec les valeurs actuelles du noyau. La structure est declaree comme suit : struct timex { int modes; /* choix du mode */ long offset; /* decalage temporel ; nanosecondes, si drapeau STA_NANO est defini, sinon microseconde*/ long freq; /* decalage de frequence ; unites, voir NOTES */ long maxerror; /* erreur maximale (microseconde) */ long esterror; /* erreur estimee (microseconde) */ int status; /* commande horloge/etat */ long constant; /* constante de temps PLL */ long precision; /* precision de l'horloge (microseconde, lecture seule) */ long tolerance; /* tolerance frequence horloge (lecture seule); unites, 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 defini, sinon microsecondes */ long tick; /* microsecondes entre tics horloge */ long ppsfreq; /* frequence PPS (pulse per second) (lecture seule) ; unites, voir NOTES */ long jitter; /* jitter PPS (lecture seule) ; nanosecondes, si drapeau etat STA_NANO defini, sinon microsecondes */ int shift; /* duree intervalle PPS (secondes, lecture seule) */ long stabil; /* stabilite PPS (lecture seule); unites, voir NOTES */ long jitcnt; /* nombre PPS depassements limite de jitter evenements (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 depassements limite stabilite evenements (lecture seule) int tai; /* decalage TAI, comme defini par l'operation ADJ_TAI (secondes, lecture seule, depuis Linux 2.6.26) */ /* octets de remplissage supplementaires pour une extension future*/ }; Le champ modes determine les parametres eventuels a ecrire (comme decrit plus loin dans cette page, les constantes pour ntp_adjtime() sont equivalentes mais ont un nom different). Il s'agit d'un masque binaire contenant une combinaison de OU binaire de zeros ou plusieurs des bits suivants : ADJ_OFFSET Definir la position de l'heure a 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 Definir la position de la frequence a 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 Definir l'erreur de temps maximale a partir de buf.maxerror. ADJ_ESTERROR Definir l'erreur de temps estimee a partir de buf.esterror. ADJ_STATUS Definir les bits de l'etat de l'horloge a partir de buf.status. Une description de ces bits est disponible ci-dessous. ADJ_TIMECONST Definir la constante PLL de l'heure a partir de buf.constant. Si le drapeau d'etat STA_NANO (voir ci-dessous) est vide, le noyau ajoute 4 a cette valeur. ADJ_SETOFFSET (depuis Linux 2.6.39) Ajouter buf.time a l'heure actuelle. Si buf.status inclut le drapeau ADJ_NANO, buf.time.tv_usec est interprete comme une valeur en nanoseconde ; sinon il est interprete en microseconde. La valeur de buf.time est la somme de ses deux champs, mais le champ buf.time.tv_usec doit toujours etre positif. L'exemple suivant montre la maniere de normaliser une timeval avec une resolution 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) Selectionner la resolution en microseconde. ADJ_NANO (depuis Linux 2.6.26) Selectionner la resolution en nanoseconde. Vous ne devriez specifier que ADJ_MICRO ou ADJ_NANO. ADJ_TAI (depuis Linux 2.6.26) Definir la position du TAI (temps atomique international) a partir de buf.constant. ADJ_TAI ne devrait pas etre utilise avec ADJ_TIMECONST, puisque le dernier mode utilise egalement le champ buf.constant. Pour une explication complete du temps atomique international (TAI) et de la difference entre ce temps et celui universel coordonne (UTC), voir BIPM ADJ_TICK Definir la valeur d'un tic a partir de buf.tick. Autrement, modes peut etre indique sous la forme de valeurs suivantes (masque multibit), auquel cas aucun autre bit ne devrait etre specifie dans modes : ADJ_OFFSET_SINGLESHOT adjtime(3) a l'ancienne : ajuster (graduellement) l'heure avec des valeurs specifiees 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 a ajuster apres une precedente operation ADJ_OFFSET_SINGLESHOT. Cette fonctionnalite a ete ajoutee dans Linux 2.6.24, mais elle ne fonctionnait pas correctement jusqu'a Linux 2.6.28. Les utilisateurs normaux sont limites a une valeur de modes nulle ou ADJ_OFFSET_SS_READ. Seul le superutilisateur peut ecrire n'importe quel parametre. Le champ buf.status est un masque de bits utilise pour definir et/ou recuperer les bits d'etat associes a l'implementation NTP. Certains bits du masque sont lisibles et modifiables, alors que d'autres ne sont qu'en lecture seule. STA_PLL (lecture-ecriture) Activer les mises a jour << phase-locked loop >> (PLL) a l'aide de ADJ_OFFSET. STA_PPSFREQ (lecture-ecriture) Activer le mode de frequence PPS (pulse-per-second ou battement par seconde). STA_PPSTIME (lecture-ecriture) Activer le mode temporel PPS. STA_FLL (lecture-ecriture) Selectionner le mode << frequency-locked loop >> (FLL). STA_INS (lecture-ecriture) Inserer un saut d'une seconde apres la derniere seconde de la journee UTC, ce qui etend ainsi la derniere minute de la journee d'une seconde. L'insertion d'un tel saut s'effectuera chaque jour tant que ce drapeau est positionne. STA_DEL (lecture-ecriture) Supprimer le saut d'une seconde a la derniere seconde de la journee UTC. Une telle suppression se produira chaque jour tant que ce drapeau est positionne. STA_UNSYNC (lecture-ecriture) Horloge non synchronisee. STA_FREQHOLD (lecture-ecriture) Conserver la frequence. Normalement, il resulte des ajustements effectues avec ADJ_OFFSET des ajustements de frequence amortis. Un seul appel corrige donc la position actuelle, mais comme les compensations dans le meme sens se repetent, les petits ajustements de frequence s'accumuleront pour corriger le decalage a long terme. Ce drapeau empeche les petits ajustements de frequence 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 present. STA_PPSJITTER (lecture seule) Fluctuation de signal (jitter) PPS excessive. STA_PPSWANDER (lecture seule) Derive de signal (wander) PPS excessive. STA_PPSERROR (lecture seule) Erreur de calibrage du signal PPS. STA_CLOCKERR (lecture seule) Erreur d'horloge materielle. STA_NANO (lecture seule ; depuis Linux 2.6.26) Resolution (0 = microseconde, 1 = nanoseconde). Positionne a l'aide de ADJ_NANO, annule a 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 inusite. Les tentatives de positionner des bits d'etat qui sont en lecture seule sont ignorees silencieusement. clock_adjtime () L'appel systeme clock_adjtime() (ajoute a Linux 2.6.39) se comporte comme adjtimex() mais il prend un parametre clk_id supplementaire pour indiquer sur quelle horloge specifique agir. ntp_adjtime () La fonction de bibliotheque ntp_adjtime() (decrite dans le << Kernel Application Program API >>, KAPI) est une interface plus portable pour effectuer la meme tache que adjtimex(). A part les points suivants, elle est identique a adjtimex() : - Les constantes utilisees dans les modes sont prefixees de << MOD_ >> au lieu de << ADJ_ >> et elles ont les memes suffixes (MOD_OFFSET, MOD_FREQUENCY, et ainsi de suite), sauf les exceptions indiquees 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 decrit dans la KAPI. VALEUR RENVOYEE S'ils reussissent, adjtimex() et ntp_adjtime() renvoient l'etat de l'horloge ; c'est-a-dire une des valeurs suivantes : TIME_OK Horloge synchronisee, aucun ajustement de saut de seconde en attente. TIME_INS Indication qu'un saut de seconde sera ajoute a la fin de la journee UTC. TIME_DEL Indication que le saut de seconde sera retire en fin de journee 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 ete terminee. Cette valeur sera renvoyee jusqu'a ce qu'une prochaine operation ADJ_STATUS ne vide les drapeaux STA_INS et STA_DEL. TIME_ERROR L'horloge systeme n'est pas synchronisee avec un serveur fiable. Cette valeur est renvoyee si un des elements suivants reste vrai : - STA_UNSYNC ou STA_CLOCKERR est defini. - STA_PPSSIGNAL est vide et soit STA_PPSFREQ, soit STA_PPSTIME est positionne. - STA_PPSTIME STA_PPSJITTER sont tous deux definis. - STA_PPSFREQ est defini et soit STA_PPSWANDER, soit STA_PPSJITTER est defini. Le nom symbolique TIME_BAD est synonyme de TIME_ERROR, fourni pour des raisons de retrocompatibilite. Remarquez qu'a partir de Linux 3.4, l'appel agit de maniere asynchrone et la valeur renvoyee ne refletera en general pas un changement d'etat provoque par l'appel lui-meme. En cas d'echec, ces appels renvoient -1 et definissent errno pour indiquer l'erreur. ERREURS EFAULT buf pointe en dehors de l'espace d'adressage accessible en ecriture. EINVAL (avant Linux 2.6.26) Vous avez essaye de positionner buf.freq sur une valeur au-dela de la plage (-33554432, +33554432). EINVAL (avant Linux 2.6.26) Vous avez essaye de positionner buf.offset sur une valeur au-dela de la plage autorisee. Avant Linux 2.0, la plage autorisee etait (-131072, +131072). Depuis Linux 2.0, la plage autorisee est (-512000, +512000). EINVAL Vous avez essaye de positionner buf.status sur une valeur differente de celles indiquees ci-dessus. EINVAL Le clk_id donne a clock_adjtime() n'est pas valable pour une de ces deux raisons. Soit la valeur positive de l'ID de l'horloge codee en dur a la maniere de System-V depasse l'intervalle, soit le clk_id dynamique ne se rapporte pas a une instance valable d'une horloge. Voir clock_gettime(2) pour un point sur les horloges dynamiques. EINVAL Une tentative a ete faite de definir buf.tick en dehors de l'intervalle 900000/HZ a 1100000/HZ, ou HZ est la frequence d'interruption de l'ordonnanceur du systeme. ENODEV Le peripherique qu'on peut brancher a chaud (comme en USB par exemple) represente par un clk_id dynamique a disparu apres avoir ete 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 privileges. Sous Linux, la capacite CAP_SYS_TIME est necessaire. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +---------------------------------+--------------------------+---------+ |Interface | Attribut | Valeur | +---------------------------------+--------------------------+---------+ |ntp_adjtime() | Securite des threads | MT-Safe | +---------------------------------+--------------------------+---------+ STANDARDS adjtimex() clock_adjtime() Linux. L'API preferee pour le demon NTP est ntp_adjtime(). NOTES Dans une structure timex, freq, ppsfreq et stabil sont des ppm (parts per million) avec une partie decimale 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 entree (dans le cas de freq) que celles en sortie. Le traitement du saut de seconde effectue 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 inserer 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" TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 adjtimex(2)