adjtimex, clock_adjtime, ntp_adjtime - Régler l'horloge du noyau (kernel
clock)
Bibliothèque C standard (
libc,
-lc)
#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);
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.
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.
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.
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.
- 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.
Pour une explication des termes utilisés dans cette section, consulter
attributes(7).
| Interface |
Attribut |
Valeur |
|
ntp_adjtime() |
Sécurité des threads |
MT-Safe |
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().
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.
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"
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]>, David Prévot <
[email protected]> et
Jean-Philippe MENGUAL <
[email protected]>
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 à
[email protected]