adjtimex
Section: System Calls (2)
Updated: 10 février 2023
Index
Return to Main Contents
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
BIPM
- ADJ_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).
Interface | Attribut | Valeur
|
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 2ha-16 ppm et
2ha16=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"
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
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 à
Index
- NOM
-
- BIBLIOTHÈQUE
-
- SYNOPSIS
-
- DESCRIPTION
-
- clock_adjtime ()
-
- ntp_adjtime ()
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- ATTRIBUTS
-
- STANDARDS
-
- NOTES
-
- VOIR AUSSI
-
- TRADUCTION
-
This document was created by
man2html,
using the manual pages.
Time: 09:20:26 GMT, May 23, 2024