Man page - clock_adjtime(2)

Packages contas this manual

Available languages:

en fr it pl ja ru de

Manual

adjtimex(2) System Calls Manual adjtimex(2)

adjtimex, clock_adjtime, ntp_adjtime - dopasowuje zegar w jądrze

Standardowa biblioteka C (libc, -lc)

#include <sys/timex.h>
int adjtimex(struct timex *buf);
int clock_adjtime(clockid_t clk_id, struct timex *buf);
int adjtimex(struct timex *buf);

Linux używa algorytmu dopasowywania Davida L. Millsa (zob. w RFC 1305). Wywołanie systemowe adjtimex czyta i opcjonalnie ustawia parametry sterujące tego algorytmu. Pobiera wskaźnik do struktury timex, aktualizuje parametry w jądrze na podstawie (wybranych) wartości przekazanych w polach i zwraca tę samą strukturę z bieżącymi ustawieniami jądra. Struktura jest zadeklarowana następująco:


struct timex {


    int  modes;      /* Wybór trybu */


    long offset;     /* Przesunięcie czasu; nanosekundy jeśli


                        ustawiono znacznik statusu STA_NANO, jeśli


                        nie - mikrosekundy */


    long freq;       /* Przesunięcie częstotliwości; zob. UWAGI


                        dotyczące jednostek */


    long maxerror;   /* Maksymalny błąd (mikrosekundy) */


    long esterror;   /* Szacowany błąd (mikrosekundy) */


    int  status;     /* Polecenie/status zegara */


    long constant;   /* Stała czasu PLL (phase-locked loop) */


    long precision;  /* Precyzja zegara


                        (mikrosekundy, tylko do odczytu) */


    long tolerance;  /* Tolerancja częstotliwości zegara (tylko do


                        odczytu); zob. UWAGI dotyczące jednostek */


    struct timeval time;


                     /* Bieżący czas (tylko do odczytu, za wyjątkiem


                        ADJ_SETOFFSET); przy powrocie time.tv_usec


                        zawiera nanosekundy jeśli ustawiono znacznik


                        statusu STA_NANO, jeśli nie - mikrosekundy */


    long tick;       /* Mikrosekundy pomiędzy impulsami zegara */


    long ppsfreq;    /* Częstotliwość PPS (pulse per second) (tylko


                        do odczytu); zob. UWAGI dot. jednostek */


    long jitter;     /* Fluktuacja PPS (tylko do odczytu); nanosek.


                        jeśli ustawiono znacznik statusu STA_NANO,


                        jeśli nie - mikrosekundy */


    int  shift;      /* Czas interwału PPS


                        (sekundy, tylko do odczytu) */


    long stabil;     /* Stabilność PPS (tylko do odczytu);


                        zob. UWAGI dotyczące jednostek */


    long jitcnt;     /* Liczba zdarzeń wykroczenia poza limit


                        fluktuacji PPS (tylko do odczytu) */


    long calcnt;     /* Liczba interwałów kalibracji PPS


                        (tylko do odczytu) */


    long errcnt;     /* Liczba interwałów błędów PPS


                        (tylko do odczytu) */


    long stbcnt;     /* Liczba zdarzeń wykroczenia poza limit


                        stabilności PPS (tylko do odczytu) */


    int tai;         /* Przesunięcie TAI, zgodnie z ustawieniem


                        poprzednią operacją ADJ_TAI (sekundy,


                        tylko do odczytu, od Linuksa 2.6.26) */


    /* Kolejne bajty wyrównania do przyszłych rozszerzeń */
};

Pole modes określa, które parametry (jeśli w ogóle) ustawić (jak opisano później w niniejszym podręczniku, stałe używane w ntp_adjtime() są równoważne, lecz inaczej nazwane). Jest to maska bitowa zawierająca sumę bitową (OR) kombinacji zera lub więcej spośród następujących bitów:

Ustawia przesunięcie czasu z buf.offset. Od Linuksa 2.6.26, podana wartość jest ograniczana do przedziału (-0.5s, +0.5s). W starszych jądrach występował błąd EINVAL, gdy podało się wartość spoza zakresu.
Ustawia przesunięcie częstotliwości z buf.freq. Od Linuksa 2.6.26, podana wartość jest ograniczana do przedziału (-32768000, +32768000). W starszych jądrach występował błąd EINVAL, gdy podało się wartość spoza zakresu.
Ustawia maksymalny błąd czasu z buf.maxerror.
Ustawia szacowany błąd czasu z buf.esterror.
Ustawia bity statusu zegara z buf.status. Niżej dostępny jest opis tych bitów.
Ustawia stałą czasu PLL z buf.constant. Jeśli znacznik statusu STA_NANO (zob. niżej) jest wyczyszczony, jądro dodaje do tej wartości 4.
Dodaje buf.time do bieżącego czasu. Jeśli buf.status obejmuje znacznik ADJ_NANO, to buf.time.tv_usec jest interpretowane jako wartość w nanosekundach, w przeciwnym razie jest interpretowane jako mikrosekundy.
Wartość buf.time jest sumą jego dwóch pól, lecz pole buf.time.tv_usec musi być zawsze nieujemne. Poniższy przykład ukazuje sposób normalizacji timeval z nanosekundową rozdzielczością.

while (buf.time.tv_usec < 0) {


    buf.time.tv_sec  -= 1;


    buf.time.tv_usec += 1000000000;
}

Wybiera rozdzielczość mikrosekundową.
Wybiera rozdzielczość nanosekundową. Powinno się użyć tylko jednego ze znaczników ADJ_MICRO lub ADJ_NANO.
Ustawia przesunięcie międzynarodowego czasu atomowego — TAI (ang. Atomic International Time) z buf.constant.
ADJ_TAI nie należy używać łącznie z ADJ_TIMECONST, ponieważ ten ostatni również używa pola buf.constant.
Pełne wytłumaczenie TAI oraz różnic między TAI i UTC, opisano na stronie BIPM
Ustawia wartość impulsu na buf.tick.

Alternatywnie, można podać modes jako jedną z następujących wartości (wielobitowej maski); wówczas w modes nie należy podawać innych bitów:

Staromodne adjtime(3): (stopniowo) dostosowuje czas przy użyciu wartości podanej w buf.offset, określającej dostosowanie w mikrosekundach.
Zwraca (w buf.offset) czas pozostały do dostosowania po wcześniejszej operacji ADJ_OFFSET_SINGLESHOT. Funkcjonalność tę dodano w Linuksie 2.6.24, lecz nie działała poprawnie do Linuksa 2.6.28.

Zwykli użytkownicy są ograniczeni do wartości 0 lub ADJ_OFFSET_SS_READ dla modes. Jedynie superużytkownik może ustawiać jakiekolwiek parametry.

Pole buf.status jest maską bitową używaną do ustawiania/pobierania bitów statusu powiązanych z implementacją NTP. Niektóre bity w masce można odczytać i ustawić, inne są tylko do odczytu.

Włącza aktualizacje phase-locked loop (PLL) za pomocą ADJ_OFFSET.
Włącza dostosowanie częstotliwości (ang. frequency discipline) PPS (pulse-per-second) .
Włącza dostosowanie czasu (ang. time discipline) PPS (pulse-per-second) .
Wybiera tryb frequency-locked loop (FLL).
Umieszcza sekundę przestępną po ostatniej sekundzie dnia UTC, wydłużając zatem ostatnią minutę dnia o jedną sekundę. Sekunda przestępna będzie występowała każdego dnia, dopóki ten znacznik pozostanie ustawiony.
Odejmuje sekundę przestępną z ostatniej sekundy dnia UTC. Odjęcie sekundy przestępnej będzie występowało każdego dnia, dopóki ten znacznik pozostanie ustawiony.
Zegar nie jest zsynchronizowany.
Utrzymuje częstotliwość. Zwykle, dostosowania częstotliwości uczynione za pomocą ADJ_OFFSET powodują również stopniowe korekcje częstotliwości. Tak więc jedno wywołanie poprawia bieżące przesunięcie, ale że przesunięcia w tym samym kierunku są czynione wielokrotnie, mniejsze dostosowania częstotliwości skumulują się poprawiając odchylenie występujące w dłuższym okresie.
Ten znacznik zapobiega wykonywaniu mniejszych dostosowań częstotliwości, przy poprawianiu wartości ADJ_OFFSET.
Dostępny jest prawidłowy sygnał PPS (pulse-per-second).
Przekroczono fluktuację sygnału PSS.
Przekroczono dryft sygnału PSS.
Błąd kalibracji sygnału PPS.
Usterka zegara sprzętowego.
Rozdzielczość (0 = mikrosekundowa, 1 = nanosekundowa). Ustawiana poprzez ADJ_NANO, czyszczona poprzez ADJ_MICRO.
Tryb (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
Źródło zegara (0 = A, 1 = B); aktualnie nieużywane.

Próby ustawienia bitów statusu tylko do odczytu są po cichu ignorowane.

Wywołanie systemowe clock_adjtime() (dodane w Linuksie 2.6.39) zachowuje się jak adjtimex(), lecz przyjmuje dodatkowy argument clk_id określający konkretny zegar, na którym ma działać.

Funkcja biblioteczna ntp_adjtime() (opisana w „Kernel Application Program API” — KAPI NTP) jest bardziej przenośnym interfejsem, wykonującym takie samo zadanie jak adjtimex(). Oprócz poniższych punktów, jest identyczne do adjtimex():

•
Stałe używane w modes mają przedrostki „MOD_” zamiast „ADJ_” i takie same przyrostki (co daje MOD_OFFSET, MOD_FREQUENCY, itd.), poza wyjątkami opisanymi poniżej.
•
MOD_CLKA jest synonimem ADJ_OFFSET_SINGLESHOT.
•
MOD_CLKB jest synonimem ADJ_TICK.
•
Brak jest synonimu dla ADJ_OFFSET_SS_READ, czego nie opisano w KAPI.

W przypadku powodzenia, adjtimex() i ntp_adjtime() zwracają stan zegara; tj. jedną z poniższych wartości:

Zegar zsynchronizowany, brak oczekującego dostosowania sekundy przestępnej.
Wskazuje, że sekunda przestępna zostanie dodana pod koniec dnia UTC.
Wskazuje, że sekunda przestępna zostanie odjęta pod koniec dnia UTC.
Trwa umieszczenie sekundy przestępnej.
Zakończono umieszczenie lub odjęcie sekundy przestępnej. Ta wartość będzie zwracana do momentu wyczyszczenia znaczników STA_INS i STA_DEL, przez następną operację ADJ_STATUS.
Zegar systemowy nie został zsynchronizowany z wiarygodnym serwerem. Wartość jest zwracana, w przypadku spełnienia dowolnego z poniższych warunków:
•
Ustawiono STA_UNSYNC albo STA_CLOCKERR.
•
STA_PPSSIGNAL jest wyczyszczony i ustawiono STA_PPSFREQ albo STA_PPSTIME.
•
Ustawiono STA_PPSTIME oraz STA_PPSJITTER.
•
Ustawiono STA_PPSFREQ i ustawiono STA_PPSWANDER albo STA_PPSJITTER.
Nazwa symboliczna TIME_BAD jest synonimem TIME_ERROR, w celu zachowania wstecznej kompatybilności.

Proszę zauważyć, że poczynając od Linuksa 3.4, wywołanie działa asynchronicznie i zwracana wartość zwykle nie oddaje zmiany stanu spowodowanej przez samo wywołanie.

W przypadku błędu, wywołania zwracają -1 i ustawiają errno wskazując błąd.

buf nie wskazuje do zapisywalnej pamięci.
Próbowano ustawić wartość buf.freq spoza przedziału (-33554432, +33554432).
Próbowano ustawić wartość buf.offset spoza dozwolonego przedziału. Przed Linuksem 2.0, dozwolony przedział wynosił (-131072, +131072). Od Linuksa 2.0, dozwolony przedział wynosił (-512000, +512000).
Próbowano ustawić buf.status na wartość inną niż opisaną powyżej.
clk_id przekazane do clock_adjtime() jest nieprawidłowe z jednego z dwóch powodów: albo dodatnia wartość identyfikatora zegara zakodowana na stałe w stylu Systemu V jest poza zakresem, albo dynamiczne clk_id nie odnosi się do prawidłowego wystąpienia obiektu zegara. Opis dynamicznych zegarów znajduje się w podręczniku clock_gettime(2).
Próbowano ustawić buf.tick na wartość spoza zakresu 900000/HZ do 1100000/HZ, gdzie HZ jest częstotliwością przerwania systemowego czasomierza.
Urządzenie umożliwiające podłączenie „na gorąco” (np. USB) reprezentowane przez dynamiczny clk_id zniknęło po otwarciu jego urządzenia znakowego. Zob. podręcznik clock_gettime(2) aby dowiedzieć się więcej o zegarach dynamicznych.
Podany clk_id nie obsługuje dostosowywania.
buf.modes nie wynosi ani 0, ani ADJ_OFFSET_SS_READ i wywołujący nie jest wystarczająco uprzywilejowany. W Linuksie wymagany jest przywilej (ang. capability) CAP_SYS_TIME.

Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku attributes(7).

Interfejs Atrybut Wartość
ntp_adjtime() Bezpieczeństwo wątkowe MT-bezpieczne

Linux.

Preferowanym API do demona NTP jest ntp_adjtime().

W strukturach timex, freq, ppsfreq i stabil występują ppm (części na milion) z 16-bitową częścią ułamkową, co oznacza, że wartość w tych polach wynosi tak naprawdę 2^-16 ppm, a 2^16=65536 jest równe 1 ppm. Jest to prawdziwe zarówno w przypadku wartości wejściowych (stosowane do freq) i wyjściowych.

Przetwarzanie sekundy przestępnej, wyzwolone przez STA_INS i STA_DEL jest dokonywane przez jądro w kontekście czasomierza. Z tego względu, zajmie to jeden impuls w sekundzie, zanim sekunda przestępna zostanie dodana lub usunięta.

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”

Tłumaczenie niniejszej strony podręcznika: Przemek Borys <pborys@dione.ids.pl>, Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.

2 maja 2024 r. Linux man-pages 6.9.1