ntp_adjtime(2) Kernel-Uhr einstellen

Other Alias

adjtimex

ÜBERSICHT

#include <sys/timex.h>
int adjtimex(struct timex *buf);
int ntp_adjtime(struct timex *buf);

BESCHREIBUNG

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;      /* Mode selector */
    long offset;     /* Time offset; nanoseconds, if STA_NANO
                        status flag is set, otherwise
                        microseconds */
    long freq;       /* Frequency offset; see NOTES for units */
    long maxerror;   /* Maximum error (microseconds) */
    long esterror;   /* Estimated error (microseconds) */
    int  status;     /* Clock command/status */
    long constant;   /* PLL (phase-locked loop) time constant */
    long precision;  /* Clock precision
                        (microseconds, read-only) */
    long tolerance;  /* Clock frequency tolerance (read-only);
                        see NOTES for units */
    struct timeval time;
                     /* Current time (read-only, except for
                        ADJ_SETOFFSET); upon return, time.tv_usec
                        contains nanoseconds, if STA_NANO status
                        flag is set, otherwise microseconds */
    long tick;       /* Microseconds between clock ticks */
    long ppsfreq;    /* PPS (pulse per second) frequency
                        (read-only); see NOTES for units */
    long jitter;     /* PPS jitter (read-only); nanoseconds, if
                        STA_NANO status flag is set, otherwise
                        microseconds */
    int  shift;      /* PPS interval duration
                        (seconds, read-only) */
    long stabil;     /* PPS stability (read-only);
                        see NOTES for units */
    long jitcnt;     /* PPS count of jitter limit exceeded
                        events (read-only) */
    long calcnt;     /* PPS count of calibration intervals
                        (read-only) */
    long errcnt;     /* PPS count of calibration errors
                        (read-only) */
    long stbcnt;     /* PPS count of stability limit exceeded
                        events (read-only) */
    int tai;         /* TAI offset, as set by previous ADJ_TAI
                        operation (seconds, read-only,
                        since Linux 2.6.26) */
    /* Further padding bytes to allow for future expansion */
};

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 ist.
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 ist.
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.29)
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.36)
Wählt Mikrosekundenauflösung.
ADJ_NANO (seit Linux 2.6.36)
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
Set tick value from 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
Old-fashioned adjtime(): (gradually) adjust time by value specified in buf.offset, which specifies an adjustment in microseconds.
ADJ_OFFSET_SS_READ (funktionell seit Linux 2.6.28)
Liefert (in buf.offset) den verbliebenen Zeitumfang zurück, der 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.

The buf.status field is a bit mask that is used to set and/or retrieve status bits associated with the NTP implementation. Some bits in the mask are both readable and settable, while others are read-only.

STA_PLL (lesen/schreiben)
Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
STA_PPSFREQ (lesen/schreiben)
Enable PPS (pulse-per-second) frequency discipline.
STA_PPSTIME (lesen/schreiben)
Enable PPS time discipline.
STA_FLL (lesen/schreiben)
Select frequency-locked loop (FLL) mode.
STA_INS (lesen/schreiben)
Insert a leap second after the last second of the UTC day, thus extending the last minute of the day by one second. Leap-second insertion will occur each day, so long as this flag remains set.
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)
Hold frequency. Normally adjustments made via ADJ_OFFSET result in dampened frequency adjustments also being made. So a single call corrects the current offset, but as offsets in the same direction are made repeatedly, the small frequency adjustments will accumulate to fix the long-term skew.

Dieser Schalter verhindert die Durchführungen der kleinen Frequenzanpassungen, wenn für einen Wert ADJ_OFFSET korrigiert wird.

STA_PPSSIGNAL (nur lesend)
A valid PPS (pulse-per-second) signal is present.
STA_PPSJITTER (nur lesend)
PPS signal jitter exceeded.
STA_PPSWANDER (nur lesend)
PPS signal wander exceeded.
STA_PPSERROR (nur lesend)
PPS signal calibration error.
STA_CLOCKERR (nur lesend)
Clock hardware fault.
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)
Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
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.

ntp_adjtime ()

The ntp_adjtime() library function (described in the NTP "Kernel Application Program API", KAPI) is a more portable interface for performing the same task as adjtimex(). Other than the following points, it is identical to adjtime():
*
The constants used in modes are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, MOD_OFFSET, MOD_FREQUENCY, and so on), other than the exceptions noted in the following points.
*
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.

RÜCKGABEWERT

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.

FEHLER

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-Zeitgebers 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.

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 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.

ATTRIBUTE

Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
SchnittstelleAttributWert
ntp_adjtime() Multithread-FähigkeitMT-Safe

KONFORM ZU

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(3).

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 4.06 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 <[email protected]>, Martin Eberhard Schauer <[email protected]>, Mario Blättermann <[email protected]> und Helge Kreutzmann <[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 <[email protected]>.

TRANSLATIONS

SIEHE AUCH

LAST GESUCHT