adjtimex, clock_adjtime, ntp_adjtime - Kernel-Uhr einstellen
Standard-C-Bibliothek (
libc,
-lc)
#include <sys/timex.h>
int adjtimex(struct timex *Puffer);
int clock_adjtime(clockid_t Uhrken, struct timex *Puffer);
int ntp_adjtime(struct timex *Puffer);
Linux verwendet den Algorithmus von David L. Mills für die Einstellung
von Uhren (siehe RFC 5905). Der Systemaufruf
adjtimex() liest
und setzt optional Einstellparameter für diesen Algorithmus. Ihm wird
ein Zeiger auf eine Struktur
timex übergeben. Aus
ausgewählten Feldwerten davon aktualisiert er Kernel-Parameter.
Abschließend wird die gleiche Struktur mit aus den aktuellen
Kernelwerten aktualisierten Parametern zurückgeliefert. Die Struktur
ist wie folgt deklariert:
struct timex {
int modes; /* Modusauswahl */
long offset; /* Zeitversatz; Nanosekunden, falls STA_NANO
Statusschalter gesetzt ist, andernfalls
Mikrosekunden */
long freq; /* Frequenzversatz; siehe ANMERKUNGEN für Einheiten */
long maxerror; /* Maximaler Fehler (Mikrosekunden) */
long esterror; /* Abgeschätzter Fehler (Mikrosekunden) */
int status; /* Uhrbefehl/-status */
long constant; /* PLL (Phasenregelschleife) Zeitkonstante */
long precision; /* Uhr-Genauigkeit
(Mikrosekunden, nur lesbar) */
long tolerance; /* Uhrfrequenztoleranz (nur lesbar);
siehe ANMERKUNGEN für Einheiten */
struct timeval time;
/* Aktuelle Zeit (nur lesbar, außer für
ADJ_SETOFFSET); nach Rückkehr enthält time.tv_usec
Nanosekunden, falls der STA_NANO-Status-
schalter gesetzt ist, andernfalls Mikrosekunden */
long tick; /* Mikrosekunden zwischen Uhr-Ticks */
long ppsfreq; /* PPS- (Impulse pro Sekunde) Frequenz
(nur lesbar); siehe ANMERKUNGEN für Einheiten */
long jitter; /* PPS-Jitter (nur lesbar); Nanosekunden, falls
STA_NANO Statusschalter gesetzt ist, andernfalls
Mikrosekunden */
int shift; /* PPS-Intervalldauer
(Sekunden, nur lesbar) */
long stabil; /* PPS-Stabilität (nur lesbar);
siehe ANMERKUNGEN für Einheiten */
long jitcnt; /* PPS-Anzahl der Ereignisse, die die
Jitter-Begrenzung überschreiten (nur lesbar) */
long calcnt; /* PPS-Anzahl der Kalibrierungsintervalle
(nur lesbar) */
long errcnt; /* PPS-Anzahl der Kalibrierungsfehler
(nur lesbar) */
long stbcnt; /* PPS-Anzahl der Ereignisse, die die
Stabilitäts-Begrenzung überschreiten (nur lesbar) */
int tai; /* TAI-Versatz, wie durch frühere ADJ_TAI-
Aktionen gesetzt (Sekunden, nur lesbar,
seit Linux 2.6.26) */
/* Weitere Füll-Bytes, um zukünftige Erweiterungen zu ermöglichen */
};
Das Feld
modes bestimmt, welche Parameter, falls vorhanden, zu setzen
sind. (Wie später auf dieser Seite beschrieben wird, sind die
Konstanten für
ntp_adjtime() äquivalent, aber anders
benannt.) Es darf eine bitweise
Oder-Verknüpfung von Null oder
mehr der folgenden Bits enthalten:
- ADJ_OFFSET
- Setzt den Zeitversatz aus Puffer.offset. Seit Linux
2.6.26 ist der bereitgestellte Wert auf den Bereich (-0.5s, +0.5s)
festgelegt. Unter älteren Kerneln tritt ein Fehler EINVAL
auf, falls der bereitgestellte Wert außerhalb des Bereichs
liegt.
- ADJ_FREQUENCY
- Setzt den Zeitversatz aus Puffer.freq. Seit Linux
2.6.26 ist der bereitgestellte Wert auf den Bereich (-32768000, +32768000)
festgelegt. Unter älteren Kerneln tritt ein Fehler EINVAL
auf, falls der bereitgestellte Wert außerhalb des Bereichs
liegt.
- ADJ_MAXERROR
- Setzt den maximalen Zeitfehler aus
Puffer.maxerror.
- ADJ_ESTERROR
- Setzt den abgeschätzten Zeitfehler aus
Puffer.esterror.
- ADJ_STATUS
- Setzt die Uhrstatus-Bits aus Puffer.status. Eine
Beschreibung dieser Bits erfolgt weiter unten.
- ADJ_TIMECONST
- Setzt die PLL-Zeitkonstante aus Puffer.constant.
Falls der Statusschalter STA_NANO (siehe unten)
zurückgesetzt ist, fügt der Kernel 4 zu diesem Wert
hinzu.
-
ADJ_SETOFFSET (seit Linux 2.6.39)
- Fügt Puffer.time zu der aktuellen Zeit hinzu.
Falls Puffer.status den Schalter ADJ_NANO enthält,
dann wird Puffer.time.tv_usec als Nanosekundenwert interpretiert;
andernfalls wird er als Mikrosekunden interpretiert.
- Der Wert von Puffer.time ist die Summe seiner zwei
Felder, aber das Feld Puffer.time.tv_usec darf nie negativ sein.
Das folgende Beispiel zeigt, wie ein timeval auf
Nanosekundenauflösung normiert wird.
-
while (Puffer.time.tv_usec < 0) {
Puffer.time.tv_sec -= 1;
Puffer.time.tv_usec += 1000000000;
}
-
ADJ_MICRO (seit Linux 2.6.26)
- Wählt Mikrosekundenauflösung.
-
ADJ_NANO (seit Linux 2.6.26)
- Wählte Nanosekundenauflösung. Nur einer von
ADJ_MICRO und ADJ_NANO sollte angegeben werden.
-
ADJ_TAI (seit Linux 2.6.26)
- Setzt den TAI- (Atomic International Time)-Versatz auf
Puffer.constant.
-
ADJ_TAI sollte nicht zusammen mit
ADJ_TIMECONST verwandt werden, da letzterer Modus auch das Feld
Puffer.constant einsetzt.
- Für eine vollständige Erklärung von
TAI und dem Unterschied zwischen TAI und UTC siehe
BIPM
- ADJ_TICK
- Setzt den Tick-Wert aus Puffer.tick.
Alternativ kann
modes als einer der folgenden (Mehrfach-Bitmasken-)Werte
angegeben werden; in diesem Fall sollten andere Bits nicht in
modes
angegeben werden:
- ADJ_OFFSET_SINGLESHOT
- Altertümliches adjtime(3): passt die Zeit
(graduell) durch den in Puffer.offset, der Anpassungen in
Mikrosekunden spezifiziert, festgelegten Wert an.
-
ADJ_OFFSET_SS_READ (funktionell seit Linux
2.6.28)
- Liefert (in Puffer.offset) die verbleibende Dauer
zurück, die nach einer früheren
ADJ_OFFSET_SINGLESHOT-Aktion noch angepasst werden muss. Diese
Funktionalität wurde in Linux 2.6.24 hinzugefügt,
funktionierte aber erst richtig ab Linux 2.6.28.
Normale Benutzer sind auf einen Wert von entweder 0 oder
ADJ_OFFSET_SS_READ für
modes eingeschränkt. Nur
der Superuser darf Parameter setzen.
Das Feld
Puffer.status ist eine Bitmaske, die zum Setzen und/oder
Abfragen von der NTP-Implementierung zugeordneten Statusbits verwandt wird.
Einige Bits in der Maske sind sowohl les- als auch setzbar, während
andere nur lesbar sind.
-
STA_PLL (lesen/schreiben)
- Aktiviert Aktualisierungen von Phasenregelschleifen (PLL)
per ADJ_OFFSET.
-
STA_PPSFREQ (lesen/schreiben)
- Aktiviert PPS- (Impulse pro Sekunde)
Frequenzeinhaltung.
-
STA_PPSTIME (lesen/schreiben)
- Aktiviert PPS (Impulse pro Sekunde) Zeiteinhaltung.
-
STA_FLL (lesen/schreiben)
- Wählt Frequenz-verriegelten- (FLL) Modus.
-
STA_INS (lesen/schreiben)
- Fügt eine Schaltsekunde nach der letzten Sekunde des
UTC-Tages ein. Damit wird die letzte Minute des Tages um eine Sekunde
verlängert. Die Einfügung von Schaltsekunden erfolgt solange
wie dieser Schalter gesetzt bleibt.
-
STA_DEL (lesen/schreiben)
- Löscht eine Schaltsekunde in der letzten Sekunde des
UTC-Tages. Schaltsekundenlöschung wird jeden Tag erfolgen, solange
dieser Schalter gesetzt bleibt.
-
STA_UNSYNC (lesen/schreiben)
- Uhr nicht synchronisiert.
-
STA_FREQHOLD (lesen/schreiben)
- Haltefrequenz. Normale Anpassungen, die über
ADJ_OFFSET gemacht wurden, führten dazu, dass auch
gedämpfte Frequenzanpassungen gemacht wurden. Daher korrigiert ein
einzelner Aufruf den derzeitigen Versatz, da Versätze jedoch in der
selben Richtung wiederholt wurden, summieren sich die kleinen
Frequenzanpassungen, um die Verzerrung über einen längeren
Zeitraum zu beheben.
- Dieser Schalter verhindert die Durchführungen der
kleinen Frequenzanpassungen, wenn für einen Wert ADJ_OFFSET
korrigiert wird.
-
STA_PPSSIGNAL (nur lesend)
- Ein gültiges PPS- (Impulse-pro-Sekunde-)Signal ist
vorhanden.
-
STA_PPSJITTER (nur lesend)
- PPS-Signal-Jitter überschritten.
-
STA_PPSWANDER (nur lesend)
- PPS-Signalwandern überschritten.
-
STA_PPSERROR (nur lesend)
- PPS-Signal-Kalibrierungsfehler.
-
STA_CLOCKERR (nur lesend)
- Uhr-Hardware-Ausnahmebehandlung.
-
STA_NANO (nur lesend; seit Linux 2.6.26)
- Auflösung (0=Mikrosekunden, 1=Nanosekunden). Gesetzt
über ADJ_NANO, entfernt über ADJ_MICRO.
-
STA_MODE (seit Linux 2.6.26)
- Modus (0 = Phasenregelschleife, 1 = Frequenz-verriegelte
Schleife).
-
STA_CLK (nur lesend; seit Linux 2.6.26)
- Uhrquelle (0=A, 1=B); derzeit nicht verwandt.
Versuche, nur lesbare
Status-Bits zu ändern, werden ohne Meldung
ignoriert.
Der Systemaufruf
clock_adjtime() (in Linux 2.6.39 hinzugefügt)
verhält sich wie
adjtimex(), akzeptiert aber ein
zusätzliches Argument
Uhrken, um die bestimmte Uhr anzugeben,
auf der agiert werden soll.
Die Bibliotheksfunktion
ntp_adjtime() (beschrieben in dem NTP
»Kernel Application Program API«, KAPI) ist eine portierbarere
Schnittstelle für die Erledigung der gleichen Aufgaben wie
adjtimex(). Abgesehen von den folgenden Punkten ist sie zu
adjtimex() identisch:
- •
- Den in modes verwandten Konstanten wird
»MOD_« statt »ADJ_« vorangestellt und sie
haben die gleichen Endungen (daher MOD_OFFSET, MOD_FREQUENCY
und so weiter), außer den in den folgenden Punkten bemerkten
Ausnahmen.
- •
-
MOD_CLKA ist das Synonym für
ADJ_OFFSET_SINGLESHOT.
- •
-
MOD_CLKB ist das Synonym für
ADJ_TICK.
- •
- Es gibt kein Synonym für ADJ_OFFSET_SS_READ,
das nicht in der KAPI beschrieben ist.
Bei Erfolg geben
adjtimex() und
ntp_adjtime() den Status der Uhr,
d.h. einen der folgenden Werte, zurück:
- TIME_OK
- Uhr synchronisiert, keine Schaltsekundenanpassung
anhängig.
- TIME_INS
- Anzeige, dass am Ende des UTC-Tages eine Schaltsekunde
hinzugefügt wird.
- TIME_DEL
- Anzeige, dass am Ende des UTC-Tages eine Schaltsekunde
entfernt wird.
- TIME_OOP
- Einfügen einer Schaltsekunde erfolgt derzeit.
- TIME_WAIT
- Es erfolgte eine Einfügung oder Entfernung einer
Schaltsekunde. Dieser Wert wird zurückgeliefert, bis die
nächste Aktion ADJ_STATUS die Schalter STA_INS und
STA_DEL zurücksetzt.
- TIME_ERROR
- Die Systemuhr ist nicht mit einem zuverlässigen
Server synchronisiert. Dieser Wert wird zurückgeliefert, solange
eines der Folgenden zutrifft:
- •
- Entweder STA_UNSYNC oder STA_CLOCKERR ist
gesetzt.
- •
-
STA_PPSSIGNAL ist nicht gesetzt und entweder
STA_PPSFREQ oder STA_PPSTIME ist gesetzt.
- •
-
STA_PPSTIME und STA_PPSJITTER sind beide
gesetzt.
- •
-
STA_PPSFREQ ist gesetzt und entweder
STA_PPSWANDER oder STA_PPSJITTER ist gesetzt.
- Der symbolische Name TIME_BAD ist ein Synonym
für TIME_ERROR, bereitgestellt zur
Rückwärtskompatibilität.
Beachten Sie, dass seit Linux 3.4 der Aufruf asynchron erfolgt und der
Rückgabewert normalerweise nicht die vom Aufruf selbst
ausgelösten Zustandsänderung wiedergibt.
Im Fehlerfall geben diese Aufrufe -1 zurück und setzen
errno, um
den Fehler anzuzeigen.
- EFAULT
-
Puffer zeigt nicht auf beschreibbaren Speicher.
-
EINVAL (vor Linux 2.6.26)
- Es wurde versucht, Puffer.freq auf einen Wert
außerhalb des Bereichs (-33554432, +33554432) zu setzen.
-
EINVAL (vor Linux 2.6.26)
- Es wurde versucht, Puffer.offset auf einen Wert
außerhalb des erlaubten Bereichs zu setzen. Vor Linux 2.0 war der
erlaubte Bereich (-131072,+131072). Seit Linux 2.0 ist der erlaubte
Bereich (-512000, +512000).
- EINVAL
- Es wurde versucht, Puffer.status auf einen anderen
als einen der aufgeführten Werte zu setzen.
- EINVAL
- Das an clock_adjtime() übergebene
Uhrken ist aus einem von zwei Gründen ungültig.
Entweder ist der hartkodierte Uhrenkennungswert gemäß
System-V außerhalb des Bereichs oder der dynamische Uhrken
bezieht sich nicht auf eine gültige Instanz eines Uhrenobjektes.
Siehe clock_gettime(2) für eine Besprechung von dynamischen
Uhren.
- EINVAL
- Es wurde versucht, Puffer.tick auf einen Wert
außerhalb des Bereichs (900000/ HZ,1100000/HZ), zu
setzen, wobei HZ die Interruptfrequenz des System-Timers ist.
- ENODEV
- Das zur Laufzeit einsteckbare Gerät (wie
beispielsweise USB), das durch eine dynamische Uhrken dargestellt
wurde, ist nach der Öffnung seines zeichenbasierten Gerätes
verschwunden. Siehe clock_gettime(2) für eine Besprechung
dynamischer Uhren.
- EOPNOTSUPP
- Das übergebene Uhrken unterstützt
keine Anpassung.
- EPERM
-
Puffer.mode ist weder 0 noch
ADJ_OFFSET_SS_READ und der aufrufende Prozess verfügt nicht
über ausreichende Privilegien. Unter Linux ist die
CAP_SYS_TIME-Capability erforderlich.
Siehe
attributes(7) für eine Erläuterung der in diesem
Abschnitt verwandten Ausdrücke.
| Schnittstelle |
Attribut |
Wert |
|
ntp_adjtime() |
Multithread-Fähigkeit |
MT-Safe |
Keiner dieser Schnittstellen ist in POSIX.1 beschrieben.
adjtimex() und
clock_adjtime() sind Linux-spezifisch und sollte
nicht in portierbaren Programmen benutzt werden.
Das bevorzugte API für den NTP-Daemon ist
ntp_adjtime().
Im Struct
timex sind
freq,
ppsfreq und
stabil ppm
(parts per million, Teile pro Million) mit einem 16-Bit-Bruchteil. Das
bedeutet, ein Wert von 1 in diesen Feldern bedeutet tatsächlich 2^-16
ppm und 2^16=65536 ist 1 ppm. Dies ist sowohl für Eingabefelder
(für
freq) und Ausgabefelder der Fall.
Die von
STA_INS und
STA_DEL ausgelöste
Schaltsekundenverarbeitung wird vom Kernel im Timer-Kontext
durchgeführt. Daher wird ein Tick in die Sekunde benötigt, damit
die Schaltsekunde eingefügt oder gelöscht wird.
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"
Die deutsche Übersetzung dieser Handbuchseite wurde von Patrick Rother
<
[email protected]>, Martin Eberhard Schauer <
[email protected]>,
Chris Leick <
[email protected]>, Helge Kreutzmann
<
[email protected]> und Mario Blättermann
<
[email protected]> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
GNU
General Public License Version 3 oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken
Sie bitte eine E-Mail an die
Mailingliste
der Übersetzer