adjtimex(2) System Calls Manual adjtimex(2) NAZWA adjtimex, clock_adjtime, ntp_adjtime - dopasowuje zegar w jadrze BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include int adjtimex(struct timex *buf); int clock_adjtime(clockid_t clk_id, struct timex *buf); int adjtimex(struct timex *buf); OPIS Linux uzywa algorytmu dopasowywania Davida L. Millsa (zob. w RFC 1305). Wywolanie systemowe adjtimex czyta i opcjonalnie ustawia parametry sterujace tego algorytmu. Pobiera wskaznik do struktury timex, aktualizuje parametry w jadrze na podstawie (wybranych) wartosci przekazanych w polach i zwraca te sama strukture z biezacymi ustawieniami jadra. Struktura jest zadeklarowana nastepujaco: struct timex { int modes; /* Wybor trybu */ long offset; /* Przesuniecie czasu; nanosekundy jesli ustawiono znacznik statusu STA_NANO, jesli nie - mikrosekundy */ long freq; /* Przesuniecie czestotliwosci; zob. UWAGI dotyczace jednostek */ long maxerror; /* Maksymalny blad (mikrosekundy) */ long esterror; /* Szacowany blad (mikrosekundy) */ int status; /* Polecenie/status zegara */ long constant; /* Stala czasu PLL (phase-locked loop) */ long precision; /* Precyzja zegara (mikrosekundy, tylko do odczytu) */ long tolerance; /* Tolerancja czestotliwosci zegara (tylko do odczytu); zob. UWAGI dotyczace jednostek */ struct timeval time; /* Biezacy czas (tylko do odczytu, za wyjatkiem ADJ_SETOFFSET); przy powrocie time.tv_usec zawiera nanosekundy jesli ustawiono znacznik statusu STA_NANO, jesli nie - mikrosekundy */ long tick; /* Mikrosekundy pomiedzy impulsami zegara */ long ppsfreq; /* Czestotliwosc PPS (pulse per second) (tylko do odczytu); zob. UWAGI dot. jednostek */ long jitter; /* Fluktuacja PPS (tylko do odczytu); nanosek. jesli ustawiono znacznik statusu STA_NANO, jesli nie - mikrosekundy */ int shift; /* Czas interwalu PPS (sekundy, tylko do odczytu) */ long stabil; /* Stabilnosc PPS (tylko do odczytu); zob. UWAGI dotyczace jednostek */ long jitcnt; /* Liczba zdarzen wykroczenia poza limit fluktuacji PPS (tylko do odczytu) */ long calcnt; /* Liczba interwalow kalibracji PPS (tylko do odczytu) */ long errcnt; /* Liczba interwalow bledow PPS (tylko do odczytu) */ long stbcnt; /* Liczba zdarzen wykroczenia poza limit stabilnosci PPS (tylko do odczytu) */ int tai; /* Przesuniecie TAI, zgodnie z ustawieniem poprzednia operacja ADJ_TAI (sekundy, tylko do odczytu, od Linuksa 2.6.26) */ /* Kolejne bajty wyrownania do przyszlych rozszerzen */ }; Pole modes okresla, ktore parametry (jesli w ogole) ustawic (jak opisano pozniej w niniejszym podreczniku, stale uzywane w ntp_adjtime() sa rownowazne, lecz inaczej nazwane). Jest to maska bitowa zawierajaca sume bitowa (OR) kombinacji zera lub wiecej sposrod nastepujacych bitow: ADJ_OFFSET Ustawia przesuniecie czasu z buf.offset. Od Linuksa 2.6.26, podana wartosc jest ograniczana do przedzialu (-0.5s, +0.5s). W starszych jadrach wystepowal blad EINVAL, gdy podalo sie wartosc spoza zakresu. ADJ_FREQUENCY Ustawia przesuniecie czestotliwosci z buf.freq. Od Linuksa 2.6.26, podana wartosc jest ograniczana do przedzialu (-32768000, +32768000). W starszych jadrach wystepowal blad EINVAL, gdy podalo sie wartosc spoza zakresu. ADJ_MAXERROR Ustawia maksymalny blad czasu z buf.maxerror. ADJ_ESTERROR Ustawia szacowany blad czasu z buf.esterror. ADJ_STATUS Ustawia bity statusu zegara z buf.status. Nizej dostepny jest opis tych bitow. ADJ_TIMECONST Ustawia stala czasu PLL z buf.constant. Jesli znacznik statusu STA_NANO (zob. nizej) jest wyczyszczony, jadro dodaje do tej wartosci 4. ADJ_SETOFFSET (od Linuksa 2.6.39) Dodaje buf.time do biezacego czasu. Jesli buf.status obejmuje znacznik ADJ_NANO, to buf.time.tv_usec jest interpretowane jako wartosc w nanosekundach, w przeciwnym razie jest interpretowane jako mikrosekundy. Wartosc buf.time jest suma jego dwoch pol, lecz pole buf.time.tv_usec musi byc zawsze nieujemne. Ponizszy przyklad ukazuje sposob normalizacji timeval z nanosekundowa rozdzielczoscia. while (buf.time.tv_usec < 0) { buf.time.tv_sec -= 1; buf.time.tv_usec += 1000000000; } ADJ_MICRO (od Linuksa 2.6.26) Wybiera rozdzielczosc mikrosekundowa. ADJ_NANO (od Linuksa 2.6.26) Wybiera rozdzielczosc nanosekundowa. Powinno sie uzyc tylko jednego ze znacznikow ADJ_MICRO lub ADJ_NANO. ADJ_TAI (od Linuksa 2.6.26) Ustawia przesuniecie miedzynarodowego czasu atomowego -- TAI (ang. Atomic International Time) z buf.constant. ADJ_TAI nie nalezy uzywac lacznie z ADJ_TIMECONST, poniewaz ten ostatni rowniez uzywa pola buf.constant. Pelne wytlumaczenie TAI oraz roznic miedzy TAI i UTC, opisano na stronie BIPM ADJ_TICK Ustawia wartosc impulsu na buf.tick. Alternatywnie, mozna podac modes jako jedna z nastepujacych wartosci (wielobitowej maski); wowczas w modes nie nalezy podawac innych bitow: ADJ_OFFSET_SINGLESHOT Staromodne adjtime(3): (stopniowo) dostosowuje czas przy uzyciu wartosci podanej w buf.offset, okreslajacej dostosowanie w mikrosekundach. ADJ_OFFSET_SS_READ (dziala od Linuksa 2.6.28) Zwraca (w buf.offset) czas pozostaly do dostosowania po wczesniejszej operacji ADJ_OFFSET_SINGLESHOT. Funkcjonalnosc te dodano w Linuksie 2.6.24, lecz nie dzialala poprawnie do Linuksa 2.6.28. Zwykli uzytkownicy sa ograniczeni do wartosci 0 lub ADJ_OFFSET_SS_READ dla modes. Jedynie superuzytkownik moze ustawiac jakiekolwiek parametry. Pole buf.status jest maska bitowa uzywana do ustawiania/pobierania bitow statusu powiazanych z implementacja NTP. Niektore bity w masce mozna odczytac i ustawic, inne sa tylko do odczytu. STA_PLL (tylko do odczytu) Wlacza aktualizacje phase-locked loop (PLL) za pomoca ADJ_OFFSET. STA_PPSFREQ (tylko do odczytu) Wlacza dostosowanie czestotliwosci (ang. frequency discipline) PPS (pulse-per-second) . STA_PPSTIME (tylko do odczytu) Wlacza dostosowanie czasu (ang. time discipline) PPS (pulse-per-second) . STA_FLL (tylko do odczytu) Wybiera tryb frequency-locked loop (FLL). STA_INS (tylko do odczytu) Umieszcza sekunde przestepna po ostatniej sekundzie dnia UTC, wydluzajac zatem ostatnia minute dnia o jedna sekunde. Sekunda przestepna bedzie wystepowala kazdego dnia, dopoki ten znacznik pozostanie ustawiony. STA_DEL (tylko do odczytu) Odejmuje sekunde przestepna z ostatniej sekundy dnia UTC. Odjecie sekundy przestepnej bedzie wystepowalo kazdego dnia, dopoki ten znacznik pozostanie ustawiony. STA_UNSYNC (tylko do odczytu) Zegar nie jest zsynchronizowany. STA_FREQHOLD (tylko do odczytu) Utrzymuje czestotliwosc. Zwykle, dostosowania czestotliwosci uczynione za pomoca ADJ_OFFSET powoduja rowniez stopniowe korekcje czestotliwosci. Tak wiec jedno wywolanie poprawia biezace przesuniecie, ale ze przesuniecia w tym samym kierunku sa czynione wielokrotnie, mniejsze dostosowania czestotliwosci skumuluja sie poprawiajac odchylenie wystepujace w dluzszym okresie. Ten znacznik zapobiega wykonywaniu mniejszych dostosowan czestotliwosci, przy poprawianiu wartosci ADJ_OFFSET. STA_PPSSIGNAL (tylko do odczytu) Dostepny jest prawidlowy sygnal PPS (pulse-per-second). STA_PPSJITTER (tylko do odczytu) Przekroczono fluktuacje sygnalu PSS. STA_PPSWANDER (tylko do odczytu) Przekroczono dryft sygnalu PSS. STA_PPSERROR (tylko do odczytu) Blad kalibracji sygnalu PPS. STA_CLOCKERR (tylko do odczytu) Usterka zegara sprzetowego. STA_NANO (tylko do odczytu; od Linuksa 2.6.26) Rozdzielczosc (0 = mikrosekundowa, 1 = nanosekundowa). Ustawiana poprzez ADJ_NANO, czyszczona poprzez ADJ_MICRO. STA_MODE (od Linuksa 2.6.26) Tryb (0 = Phase Locked Loop, 1 = Frequency Locked Loop). STA_CLK (tylko do odczytu; od Linuksa 2.6.26) Zrodlo zegara (0 = A, 1 = B); aktualnie nieuzywane. Proby ustawienia bitow statusu tylko do odczytu sa po cichu ignorowane. clock_adjtime () Wywolanie systemowe clock_adjtime() (dodane w Linuksie 2.6.39) zachowuje sie jak adjtimex(), lecz przyjmuje dodatkowy argument clk_id okreslajacy konkretny zegar, na ktorym ma dzialac. ntp_adjtime () Funkcja biblioteczna ntp_adjtime() (opisana w ,,Kernel Application Program API" -- KAPI NTP) jest bardziej przenosnym interfejsem, wykonujacym takie samo zadanie jak adjtimex(). Oprocz ponizszych punktow, jest identyczne do adjtimex(): o Stale uzywane w modes maja przedrostki ,,MOD_" zamiast ,,ADJ_" i takie same przyrostki (co daje MOD_OFFSET, MOD_FREQUENCY, itd.), poza wyjatkami opisanymi ponizej. o MOD_CLKA jest synonimem ADJ_OFFSET_SINGLESHOT. o MOD_CLKB jest synonimem ADJ_TICK. o Brak jest synonimu dla ADJ_OFFSET_SS_READ, czego nie opisano w KAPI. WARTOSC ZWRACANA W przypadku powodzenia, adjtimex() i ntp_adjtime() zwracaja stan zegara; tj. jedna z ponizszych wartosci: TIME_OK Zegar zsynchronizowany, brak oczekujacego dostosowania sekundy przestepnej. TIME_INS Wskazuje, ze sekunda przestepna zostanie dodana pod koniec dnia UTC. TIME_DEL Wskazuje, ze sekunda przestepna zostanie odjeta pod koniec dnia UTC. TIME_OOP Trwa umieszczenie sekundy przestepnej. TIME_WAIT Zakonczono umieszczenie lub odjecie sekundy przestepnej. Ta wartosc bedzie zwracana do momentu wyczyszczenia znacznikow STA_INS i STA_DEL, przez nastepna operacje ADJ_STATUS. TIME_ERROR Zegar systemowy nie zostal zsynchronizowany z wiarygodnym serwerem. Wartosc jest zwracana, w przypadku spelnienia dowolnego z ponizszych warunkow: o Ustawiono STA_UNSYNC albo STA_CLOCKERR. o STA_PPSSIGNAL jest wyczyszczony i ustawiono STA_PPSFREQ albo STA_PPSTIME. o Ustawiono STA_PPSTIME oraz STA_PPSJITTER. o Ustawiono STA_PPSFREQ i ustawiono STA_PPSWANDER albo STA_PPSJITTER. Nazwa symboliczna TIME_BAD jest synonimem TIME_ERROR, w celu zachowania wstecznej kompatybilnosci. Prosze zauwazyc, ze poczynajac od Linuksa 3.4, wywolanie dziala asynchronicznie i zwracana wartosc zwykle nie oddaje zmiany stanu spowodowanej przez samo wywolanie. W przypadku bledu, wywolania zwracaja -1 i ustawiaja errno wskazujac blad. BLEDY EFAULT buf nie wskazuje do zapisywalnej pamieci. EINVAL (przed Linuksem 2.6.26) Probowano ustawic wartosc buf.freq spoza przedzialu (-33554432, +33554432). EINVAL (przed Linuksem 2.6.26) Probowano ustawic wartosc buf.offset spoza dozwolonego przedzialu. Przed Linuksem 2.0, dozwolony przedzial wynosil (-131072, +131072). Od Linuksa 2.0, dozwolony przedzial wynosil (-512000, +512000). EINVAL Probowano ustawic buf.status na wartosc inna niz opisana powyzej. EINVAL clk_id przekazane do clock_adjtime() jest nieprawidlowe z jednego z dwoch powodow: albo dodatnia wartosc identyfikatora zegara zakodowana na stale w stylu Systemu V jest poza zakresem, albo dynamiczne clk_id nie odnosi sie do prawidlowego wystapienia obiektu zegara. Opis dynamicznych zegarow znajduje sie w podreczniku clock_gettime(2). EINVAL Probowano ustawic buf.tick na wartosc spoza zakresu 900000/HZ do 1100000/HZ, gdzie HZ jest czestotliwoscia przerwania systemowego czasomierza. ENODEV Urzadzenie umozliwiajace podlaczenie ,,na goraco" (np. USB) reprezentowane przez dynamiczny clk_id zniknelo po otwarciu jego urzadzenia znakowego. Zob. podrecznik clock_gettime(2) aby dowiedziec sie wiecej o zegarach dynamicznych. EOPNOTSUPP Podany clk_id nie obsluguje dostosowywania. EPERM buf.modes nie wynosi ani 0, ani ADJ_OFFSET_SS_READ i wywolujacy nie jest wystarczajaco uprzywilejowany. W Linuksie wymagany jest przywilej (ang. capability) CAP_SYS_TIME. ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +---------------------------+--------------------------+---------------+ |Interfejs | Atrybut | Wartosc | +---------------------------+--------------------------+---------------+ |ntp_adjtime() | Bezpieczenstwo watkowe | MT-bezpieczne | +---------------------------+--------------------------+---------------+ STANDARDY adjtimex() clock_adjtime() Linux. Preferowanym API do demona NTP jest ntp_adjtime(). UWAGI W strukturach timex, freq, ppsfreq i stabil wystepuja ppm (czesci na milion) z 16-bitowa czescia ulamkowa, co oznacza, ze wartosc w tych polach wynosi tak naprawde 2^-16 ppm, a 2^16=65536 jest rowne 1 ppm. Jest to prawdziwe zarowno w przypadku wartosci wejsciowych (stosowane do freq) i wyjsciowych. Przetwarzanie sekundy przestepnej, wyzwolone przez STA_INS i STA_DEL jest dokonywane przez jadro w kontekscie czasomierza. Z tego wzgledu, zajmie to jeden impuls w sekundzie, zanim sekunda przestepna zostanie dodana lub usunieta. ZOBACZ TAKZE 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" TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Przemek Borys , Andrzej Krzysztofowicz i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.9.1 2 maja 2024 r. adjtimex(2)