adjtimex, ntp_adjtime - Kernel-Uhr einstellen
ÜBERSICHT
#include <sys/timex.h>
int adjtimex(struct timex *buf);
int ntp_adjtime(struct timex *buf);
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 buf.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 buf.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 buf.maxerror.
- ADJ_ESTERROR
- Setzt den abgeschätzten Zeitfehler aus buf.esterror.
- ADJ_STATUS
- Setzt die Uhrstatus-Bits aus buf.status. Eine Beschreibung dieser
Bits erfolgt weiter unten.
- ADJ_TIMECONST
- Setzt die PLL-Zeitkonstante aus buf.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 buf.time zu der aktuellen Zeit hinzu. Falls
buf.status den Schalter ADJ_NANO enthält, dann wird
buf.time.tv_usec als Nanosekundenwert interpretiert; andernfalls
wird er als Mikrosekunden interpretiert.
- 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 festgelegt werden.
- ADJ_TAI (seit
Linux 2.6.26)
- Setzt den TAI- (Atomic International Time)-Versatz auf
buf.constant.
- ADJ_TAI sollte nicht zusammen mit ADJ_TIMECONST verwandt
werden, da letzterer Modus auch das Feld buf.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 buf.tick.
Alternativ kann modes als einer der folgenden
(Mehrfach-Bitmasken-)Werte festgelegt werden; in diesem Fall sollten andere
Bits nicht in modes festgelegt werden:
- ADJ_OFFSET_SINGLESHOT
- Altertümliches adjtime(): passt die Zeit (graduell) durch
den in buf.offset, der Anpassungen in Mikrosekunden spezifiziert,
festgelegten Wert an.
- ADJ_OFFSET_SS_READ
(funktionell seit Linux 2.6.28)
- Liefert (in buf.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 buf.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-Fehler.
- 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.
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
adjtime() 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.
- EFAULT
- buf zeigt nicht auf beschreibbaren Speicher.
- EINVAL (Kernel vor
Linux 2.6.26)
- Es wurde versucht, buf.freq auf einen Wert außerhalb des
Bereichs (-33554432, +33554432) zu setzen.
- EINVAL (Kernel
vor Linux 2.6.26)
- Es wurde versucht, buf.offset auf einen Wert außerhalb des
erlaubten Bereichs zu setzen. In Kerneln vor Linux 2.0 war der erlaubte
Bereich (-131072,+131072). Seit Linux 2.0 ist der erlaubte Bereich
(-512000, +512000).
- EINVAL
- Es wurde versucht, buf.status auf einen anderen als einen der
aufgeführten Werte zu setzen.
- EINVAL
- Es wurde versucht, buf.tick auf einen Wert außerhalb des
Bereichs (900000/HZ,1100000/HZ), zu setzen, wobei HZ
die Interruptfrequenz des System-Timers ist.
- EPERM
- buf.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() ist 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.
Diese Seite ist Teil der Veröffentlichung 4.16 des Projekts
Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
finden sich unter https://www.kernel.org/doc/man-pages/.
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von
Patrick Rother <krd@gulu.net>, Martin Eberhard Schauer
<Martin.E.Schauer@gmx.de>, Chris Leick <c.leick@vollbio.de>,
Helge Kreutzmann <debian@helgefjell.de> und Mario Blättermann
<mario.blaettermann@gmail.com> 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
<debian-l10n-german@lists.debian.org>.