Provided by: manpages-pl-dev_4.25.1-1_all 
NAZWA
adjtimex, clock_adjtime, ntp_adjtime - dopasowuje zegar w jądrze
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
SKŁADNIA
#include <sys/timex.h>
int adjtimex(struct timex *buf);
int clock_adjtime(clockid_t clk_id, struct timex *buf);
int adjtimex(struct timex *buf);
OPIS
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:
ADJ_OFFSET
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.
ADJ_FREQUENCY
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.
ADJ_MAXERROR
Ustawia maksymalny błąd czasu z buf.maxerror.
ADJ_ESTERROR
Ustawia szacowany błąd czasu z buf.esterror.
ADJ_STATUS
Ustawia bity statusu zegara z buf.status. Niżej dostępny jest opis tych bitów.
ADJ_TIMECONST
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.
ADJ_SETOFFSET (od Linuksa 2.6.39)
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;
}
ADJ_MICRO (od Linuksa 2.6.26)
Wybiera rozdzielczość mikrosekundową.
ADJ_NANO (od Linuksa 2.6.26)
Wybiera rozdzielczość nanosekundową. Powinno się użyć tylko jednego ze znaczników ADJ_MICRO lub
ADJ_NANO.
ADJ_TAI (od Linuksa 2.6.26)
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
⟨http://www.bipm.org/en/bipm/tai/tai.html⟩
ADJ_TICK
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:
ADJ_OFFSET_SINGLESHOT
Staromodne adjtime(3): (stopniowo) dostosowuje czas przy użyciu wartości podanej w buf.offset,
określającej dostosowanie w mikrosekundach.
ADJ_OFFSET_SS_READ (działa od Linuksa 2.6.28)
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.
STA_PLL (tylko do odczytu)
Włącza aktualizacje phase-locked loop (PLL) za pomocą ADJ_OFFSET.
STA_PPSFREQ (tylko do odczytu)
Włącza dostosowanie częstotliwości (ang. frequency discipline) PPS (pulse-per-second) .
STA_PPSTIME (tylko do odczytu)
Włącza 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 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.
STA_DEL (tylko do odczytu)
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.
STA_UNSYNC (tylko do odczytu)
Zegar nie jest zsynchronizowany.
STA_FREQHOLD (tylko do odczytu)
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.
STA_PPSSIGNAL (tylko do odczytu)
Dostępny jest prawidłowy sygnał PPS (pulse-per-second).
STA_PPSJITTER (tylko do odczytu)
Przekroczono fluktuację sygnału PSS.
STA_PPSWANDER (tylko do odczytu)
Przekroczono dryft sygnału PSS.
STA_PPSERROR (tylko do odczytu)
Błąd kalibracji sygnału PPS.
STA_CLOCKERR (tylko do odczytu)
Usterka zegara sprzętowego.
STA_NANO (tylko do odczytu; od Linuksa 2.6.26)
Rozdzielczość (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)
Źródło zegara (0 = A, 1 = B); aktualnie nieużywane.
Próby ustawienia bitów statusu tylko do odczytu są po cichu ignorowane.
clock_adjtime ()
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ć.
ntp_adjtime ()
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.
WARTOŚĆ ZWRACANA
W przypadku powodzenia, adjtimex() i ntp_adjtime() zwracają stan zegara; tj. jedną z poniższych wartości:
TIME_OK Zegar zsynchronizowany, brak oczekującego dostosowania sekundy przestępnej.
TIME_INS Wskazuje, że sekunda przestępna zostanie dodana pod koniec dnia UTC.
TIME_DEL Wskazuje, że sekunda przestępna zostanie odjęta pod koniec dnia UTC.
TIME_OOP Trwa umieszczenie sekundy przestępnej.
TIME_WAIT 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.
TIME_ERROR 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.
BŁĘDY
EFAULT buf nie wskazuje do zapisywalnej pamięci.
EINVAL (przed Linuksem 2.6.26)
Próbowano ustawić wartość buf.freq spoza przedziału (-33554432, +33554432).
EINVAL (przed Linuksem 2.6.26)
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).
EINVAL Próbowano ustawić buf.status na wartość inną niż opisaną powyżej.
EINVAL 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).
EINVAL Próbowano ustawić buf.tick na wartość spoza zakresu 900000/HZ do 1100000/HZ, gdzie HZ jest
częstotliwością przerwania systemowego czasomierza.
ENODEV 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.
EOPNOTSUPP
Podany clk_id nie obsługuje dostosowywania.
EPERM 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.
ATRYBUTY
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 │ └───────────────────────────────────────────────────────────────┴────────────────────────┴───────────────┘
STANDARDY
adjtimex()
clock_adjtime()
Linux.
Preferowanym API do demona NTP jest ntp_adjtime().
UWAGI
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.
ZOBACZ TAKŻE
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” ⟨http://www.slac.stanford.edu/comp/unix/package/rtems/src/ ssrlApps/ntpNanoclock/api.htm⟩
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: 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 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.