adjtimex(2) System Calls Manual adjtimex(2) BEZEICHNUNG adjtimex, clock_adjtime, ntp_adjtime - Kernel-Uhr einstellen BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include int adjtimex(struct timex *Puffer); int clock_adjtime(clockid_t Uhrken, struct timex *Puffer); int ntp_adjtime(struct timex *Puffer); BESCHREIBUNG Linux verwendet den Algorithmus von David L. Mills fur die Einstellung von Uhren (siehe RFC 5905). Der Systemaufruf adjtimex() liest und setzt optional Einstellparameter fur diesen Algorithmus. Ihm wird ein Zeiger auf eine Struktur timex ubergeben. Aus ausgewahlten Feldwerten davon aktualisiert er Kernel-Parameter. Abschliessend wird die gleiche Struktur mit aus den aktuellen Kernelwerten aktualisierten Parametern zuruckgeliefert. 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 fur Einheiten */ long maxerror; /* Maximaler Fehler (Mikrosekunden) */ long esterror; /* Abgeschatzter 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 fur Einheiten */ struct timeval time; /* Aktuelle Zeit (nur lesbar, ausser fur ADJ_SETOFFSET); nach Ruckkehr enthalt 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 fur 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-Stabilitat (nur lesbar); siehe ANMERKUNGEN fur Einheiten */ long jitcnt; /* PPS-Anzahl der Ereignisse, die die Jitter-Begrenzung uberschreiten (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 Stabilitats-Begrenzung uberschreiten (nur lesbar) */ int tai; /* TAI-Versatz, wie durch fruhere ADJ_TAI- Aktionen gesetzt (Sekunden, nur lesbar, seit Linux 2.6.26) */ /* Weitere Full-Bytes, um zukunftige Erweiterungen zu ermoglichen */ }; Das Feld modes bestimmt, welche Parameter, falls vorhanden, zu setzen sind. (Wie spater auf dieser Seite beschrieben wird, sind die Konstanten fur ntp_adjtime() aquivalent, aber anders benannt.) Es darf eine bitweise Oder-Verknupfung 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 alteren Kerneln tritt ein Fehler EINVAL auf, falls der bereitgestellte Wert ausserhalb 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 alteren Kerneln tritt ein Fehler EINVAL auf, falls der bereitgestellte Wert ausserhalb des Bereichs liegt. ADJ_MAXERROR Setzt den maximalen Zeitfehler aus Puffer.maxerror. ADJ_ESTERROR Setzt den abgeschatzten 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) zuruckgesetzt ist, fugt der Kernel 4 zu diesem Wert hinzu. ADJ_SETOFFSET (seit Linux 2.6.39) Fugt Puffer.time zu der aktuellen Zeit hinzu. Falls Puffer.status den Schalter ADJ_NANO enthalt, 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 Nanosekundenauflosung 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) Wahlt Mikrosekundenauflosung. ADJ_NANO (seit Linux 2.6.26) Wahlte Nanosekundenauflosung. 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. Fur eine vollstandige Erklarung 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 Altertumliches 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 zuruck, die nach einer fruheren ADJ_OFFSET_SINGLESHOT-Aktion noch angepasst werden muss. Diese Funktionalitat wurde in Linux 2.6.24 hinzugefugt, funktionierte aber erst richtig ab Linux 2.6.28. Normale Benutzer sind auf einen Wert von entweder 0 oder ADJ_OFFSET_SS_READ fur modes eingeschrankt. 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, wahrend 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) Wahlt Frequenz-verriegelten- (FLL) Modus. STA_INS (lesen/schreiben) Fugt eine Schaltsekunde nach der letzten Sekunde des UTC-Tages ein. Damit wird die letzte Minute des Tages um eine Sekunde verlangert. Die Einfugung von Schaltsekunden erfolgt solange wie dieser Schalter gesetzt bleibt. STA_DEL (lesen/schreiben) Loscht eine Schaltsekunde in der letzten Sekunde des UTC-Tages. Schaltsekundenloschung wird jeden Tag erfolgen, solange dieser Schalter gesetzt bleibt. STA_UNSYNC (lesen/schreiben) Uhr nicht synchronisiert. STA_FREQHOLD (lesen/schreiben) Haltefrequenz. Normale Anpassungen, die uber ADJ_OFFSET gemacht wurden, fuhrten dazu, dass auch gedampfte Frequenzanpassungen gemacht wurden. Daher korrigiert ein einzelner Aufruf den derzeitigen Versatz, da Versatze jedoch in der selben Richtung wiederholt wurden, summieren sich die kleinen Frequenzanpassungen, um die Verzerrung uber einen langeren Zeitraum zu beheben. Dieser Schalter verhindert die Durchfuhrungen der kleinen Frequenzanpassungen, wenn fur einen Wert ADJ_OFFSET korrigiert wird. STA_PPSSIGNAL (nur lesend) Ein gultiges PPS- (Impulse-pro-Sekunde-)Signal ist vorhanden. STA_PPSJITTER (nur lesend) PPS-Signal-Jitter uberschritten. STA_PPSWANDER (nur lesend) PPS-Signalwandern uberschritten. STA_PPSERROR (nur lesend) PPS-Signal-Kalibrierungsfehler. STA_CLOCKERR (nur lesend) Uhr-Hardware-Ausnahmebehandlung. STA_NANO (nur lesend; seit Linux 2.6.26) Auflosung (0=Mikrosekunden, 1=Nanosekunden). Gesetzt uber ADJ_NANO, entfernt uber 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 andern, werden ohne Meldung ignoriert. clock_adjtime () Der Systemaufruf clock_adjtime() (in Linux 2.6.39 hinzugefugt) verhalt sich wie adjtimex(), akzeptiert aber ein zusatzliches Argument Uhrken, um die bestimmte Uhr anzugeben, auf der agiert werden soll. ntp_adjtime () Die Bibliotheksfunktion ntp_adjtime() (beschrieben in dem NTP >>Kernel Application Program API<<, KAPI) ist eine portierbarere Schnittstelle fur die Erledigung der gleichen Aufgaben wie adjtimex(). Abgesehen von den folgenden Punkten ist sie zu adjtimex() identisch: o Den in modes verwandten Konstanten wird >>MOD_<< statt >>ADJ_<< vorangestellt und sie haben die gleichen Endungen (daher MOD_OFFSET, MOD_FREQUENCY und so weiter), ausser den in den folgenden Punkten bemerkten Ausnahmen. o MOD_CLKA ist das Synonym fur ADJ_OFFSET_SINGLESHOT. o MOD_CLKB ist das Synonym fur ADJ_TICK. o Es gibt kein Synonym fur ADJ_OFFSET_SS_READ, das nicht in der KAPI beschrieben ist. RUCKGABEWERT Bei Erfolg geben adjtimex() und ntp_adjtime() den Status der Uhr, d.h. einen der folgenden Werte, zuruck: TIME_OK Uhr synchronisiert, keine Schaltsekundenanpassung anhangig. TIME_INS Anzeige, dass am Ende des UTC-Tages eine Schaltsekunde hinzugefugt wird. TIME_DEL Anzeige, dass am Ende des UTC-Tages eine Schaltsekunde entfernt wird. TIME_OOP Einfugen einer Schaltsekunde erfolgt derzeit. TIME_WAIT Es erfolgte eine Einfugung oder Entfernung einer Schaltsekunde. Dieser Wert wird zuruckgeliefert, bis die nachste Aktion ADJ_STATUS die Schalter STA_INS und STA_DEL zurucksetzt. TIME_ERROR Die Systemuhr ist nicht mit einem zuverlassigen Server synchronisiert. Dieser Wert wird zuruckgeliefert, solange eines der Folgenden zutrifft: o Entweder STA_UNSYNC oder STA_CLOCKERR ist gesetzt. o STA_PPSSIGNAL ist nicht gesetzt und entweder STA_PPSFREQ oder STA_PPSTIME ist gesetzt. o STA_PPSTIME und STA_PPSJITTER sind beide gesetzt. o STA_PPSFREQ ist gesetzt und entweder STA_PPSWANDER oder STA_PPSJITTER ist gesetzt. Der symbolische Name TIME_BAD ist ein Synonym fur TIME_ERROR, bereitgestellt zur Ruckwartskompatibilitat. Beachten Sie, dass seit Linux 3.4 der Aufruf asynchron erfolgt und der Ruckgabewert normalerweise nicht die vom Aufruf selbst ausgelosten Zustandsanderung wiedergibt. Im Fehlerfall geben diese Aufrufe -1 zuruck und setzen errno, um den Fehler anzuzeigen. FEHLER EFAULT Puffer zeigt nicht auf beschreibbaren Speicher. EINVAL (vor Linux 2.6.26) Es wurde versucht, Puffer.freq auf einen Wert ausserhalb des Bereichs (-33554432, +33554432) zu setzen. EINVAL (vor Linux 2.6.26) Es wurde versucht, Puffer.offset auf einen Wert ausserhalb 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 aufgefuhrten Werte zu setzen. EINVAL Das an clock_adjtime() ubergebene Uhrken ist aus einem von zwei Grunden ungultig. Entweder ist der hartkodierte Uhrenkennungswert gemass System-V ausserhalb des Bereichs oder der dynamische Uhrken bezieht sich nicht auf eine gultige Instanz eines Uhrenobjektes. Siehe clock_gettime(2) fur eine Besprechung von dynamischen Uhren. EINVAL Es wurde versucht, Puffer.tick auf einen Wert ausserhalb des Bereichs (900000/HZ,1100000/HZ), zu setzen, wobei HZ die Interruptfrequenz des System-Timers ist. ENODEV Das zur Laufzeit einsteckbare Gerat (wie beispielsweise USB), das durch eine dynamische Uhrken dargestellt wurde, ist nach der Offnung seines zeichenbasierten Gerates verschwunden. Siehe clock_gettime(2) fur eine Besprechung dynamischer Uhren. EOPNOTSUPP Das ubergebene Uhrken unterstutzt keine Anpassung. EPERM Puffer.mode ist weder 0 noch ADJ_OFFSET_SS_READ und der aufrufende Prozess verfugt nicht uber ausreichende Privilegien. Unter Linux ist die CAP_SYS_TIME-Capability erforderlich. ATTRIBUTE Siehe attributes(7) fur eine Erlauterung der in diesem Abschnitt verwandten Ausdrucke. +--------------------------------+-------------------------+-----------+ |Schnittstelle | Attribut | Wert | +--------------------------------+-------------------------+-----------+ |ntp_adjtime() | Multithread-Fahigkeit | MT-Sicher | +--------------------------------+-------------------------+-----------+ STANDARDS adjtimex() clock_adjtime() Linux. Das bevorzugte API fur den NTP-Daemon ist ntp_adjtime(). ANMERKUNGEN 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 tatsachlich 2^-16 ppm und 2^16=65536 ist 1 ppm. Dies ist sowohl fur Eingabefelder (fur freq) und Ausgabefelder der Fall. Die von STA_INS und STA_DEL ausgeloste Schaltsekundenverarbeitung wird vom Kernel im Timer-Kontext durchgefuhrt. Daher wird ein Tick in die Sekunde benotigt, damit die Schaltsekunde eingefugt oder geloscht wird. SIEHE AUCH 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" UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Patrick Rother , Martin Eberhard Schauer , Chris Leick , Helge Kreutzmann und Mario Blattermann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.06 31. Oktober 2023 adjtimex(2)