ADJTIMEX
Section: Linux Programmer's Manual (2)
Updated: 2020-06-09
Index
Return to Main Contents
名前
adjtimex, clock_adjtime, ntp_adjtime - カーネルの時計を調整する
書式
#include <sys/timex.h>
int adjtimex(struct timex *buf);
int clock_adjtime(clockid_t clk_id, struct timex *buf);
int ntp_adjtime(struct timex *buf);
説明
Linux は David L. Mill の時計調節アルゴリズムを使用している (RFC 5905 を参照)。
システムコール
adjtimex()
はこのアルゴリズムの調節のパラメーターを読み取ったり、設定したりする。
この関数は timex
構造体へのポインターを受け取り、(選択された) フィールド値でカーネルのパラメーターを更新して、
現在のカーネルの値で更新された同じ構造体を返す。
この構造体は以下のように宣言される:
struct timex {
int modes; /* モードの選択 */
long offset; /* 時刻オフセット; STA_NANO ステータスフラグが
設定されるとナノ秒で、それ以外はマイクロ秒 */
long freq; /* 周波数オフセット。 単位は「注意」を参照 */
long maxerror; /* 最大エラー (マイクロ秒) */
long esterror; /* 推定エラー (マイクロ秒) */
int status; /* クロックコマンド/ステータス */
long constant; /* PLL (phase-locked loop) 時刻定数 */
long precision; /* クロック精度 (マイクロ秒、読み出し専用) */
long tolerance; /* クロック周波数耐性 (読み出し専用)
単位は「注意」を参照 */
struct timeval time;
/* 現在時刻 (読み出し専用、 ADJ_SETOFFSET の
場合以外); リターン時は time.tv_usec は
STA_NANO ステータスフラグが設定されると
ナノ秒で、それ以外はマイクロ秒 */
long tick; /* クロック tick 間のマイクロ秒 */
long ppsfreq; /* PPS (pulse per second) 周波数 (読み出し専用)
単位は「注意」を参照 */
long jitter; /* PPS ジッター (読み出し専用); STA_NANO
ステータスフラグが設定されるとナノ秒、
それ以外はマイクロ秒 */
int shift; /* PPS interval duration (秒、読み出し専用) */
long stabil; /* PPS 安定性 (読み出し専用)
単位は「注意」を参照、 */
long jitcnt; /* ジッター上限超過イベントの PPS カウント
(読み出し専用) */
long calcnt; /* 校正間隔の PPS カウント (読み出し専用) */
long errcnt; /* 校正エラーの PPS カウント (読み出し専用) */
long stbcnt; /* 安定性上限超過イベントの PPS カウント
(読み出し専用) */
int tai; /* TAI オフセット、直前の ADJ_TAI 命令で設定
したもの (秒、読み出し専用、
Linux 2.6.26 以降) */
/* これ以降のパディングバイトは将来の拡張用である */
};
modes
フィールドは (必要に応じて) どのパラメーターを設定するか決定する。
(このページの後の方で説明するように、
ntp_adjtime()
で使われる定数は等しいが、異なる名前になっている。)
modes
は、以下のビット値の 0 個以上のビット
OR
からなるビットマスクである:
- ADJ_OFFSET
-
buf.offset を時刻オフセットを設定する。
Linux 2.6.26 以降では、
指定された値は (-0.5s, +0.5s) の範囲にされる。
古いカーネルでは、指定された値が範囲外の場合、
EINVAL
エラーが起こる。
- ADJ_FREQUENCY
-
buf.freq を周波数オフセットを設定する。
Linux 2.6.26 以降では、
指定された値は (-32768000, +32768000) の範囲にされる。
古いカーネルでは、指定された値が範囲外の場合、
EINVAL
エラーが起こる。
- ADJ_MAXERROR
-
buf.maxerror を最大時刻エラーを設定する。
- ADJ_ESTERROR
-
buf.esterror を推定時刻エラー (estimated time error) を設定する。
- ADJ_STATUS
-
buf.status
をクロックステータスビットを設定する。
このビットの説明は以下でする。
- ADJ_TIMECONST
-
buf.constant を PLL の時刻定数を設定する。 (下記の) STA_NANO ステータスフラグがクリアされた場合、
カーネルはこの値に 4 を足す。
-
-
ADJ_SETOFFSET (Linux 2.6.39 以降)
buf.time を現在時刻に加算する。 buf.status に ADJ_NANO フラグが指定された場合、
buf.time.tv_usec はナノ秒として解釈される。 そうでない場合はマイクロ秒として解釈される。
-
buf.time
の値は、2 つのフィールドの合計であるが、フィールド
buf.time.tv_usec
は非負でなければならない。
以下の例では、
timeval
をナノ秒の精度に正規化する方法を示している。
while (buf.time.tv_usec < 0) {
buf.time.tv_sec -= 1;
buf.time.tv_usec += 1000000000;
}
-
-
ADJ_MICRO (Linux 2.6.26 以降)
マイクロ秒単位の精度を選択する。
-
-
ADJ_NANO (Linux 2.6.26 以降)
ナノ秒単位の精度を選択する。 ADJ_MICRO と ADJ_NANO の一方のみを指定すること。
- ADJ_TAI (Linux 2.6.26 以降)
-
buf.constant
を TAI (Atomic International Time) オフセットを設定する。
-
ADJ_TAI
は
ADJ_TIMECONST
と組み合わせて使わないこと。
ADJ_TIMECONST
も
buf.constant
フィールド利用するからである。
-
TAI の詳細な説明および TAI と UTC の違いについては
BIPM
を参照。
- ADJ_TICK
-
buf.tick を tick 値に設定する。
上記の代わりに、 modes に以下の値 (複数ビットのマスク) のいずれかを指定することもできる。 この場合は他のビットは modes
に指定すべきではない。
- ADJ_OFFSET_SINGLESHOT
-
古い形式の
adjtime(3):
時刻を
buf.offset
で指定された値で (徐々に) 調整する。
buf.offset
はマイクロ秒単位の調整値である。
- ADJ_OFFSET_SS_READ (Linux 2.6.28 以降で機能する)
-
ADJ_OFFSET_SINGLESHOT 操作を行った後でまだ残っている調整すべき時刻量を (buf.offset で) 返す。
この機能は Linux 2.6.24 で追加されたが、 Linux 2.6.28 までは正常に動作しなかった。
通常のユーザーは modes の値は 0 か ADJ_OFFSET_SS_READ のいずれかに制限されている。
スーパーユーザーのみが全てのパラメーターを設定できる。
buf.status フィールドはビットマスクで、
このフィールドを使って NTP 実装に関連するステータスビットの設定や取得を行うことができる。
マスクのビットのいくつかは読み書き両用で、他のビットは読み出し専用である。
-
-
STA_PLL (読み書き両用)
Phase Locked Loop (PLL) の更新を有効にする。
ADJ_OFFSET
経由で設定できる。
-
-
STA_PPSFREQ (読み書き両用)
PPS (pulse-per-second) freq discipline を有効にする。
-
-
STA_PPSTIME (読み書き両用)
PPS time discipline を有効にする。
-
-
STA_FLL (読み書き両用)
Frequency Locked Loop (FLL) モードを選択する。
-
-
STA_INS (読み書き両用)
UTC 日付の最後の秒の後に、閏秒を挿入する。
よって日付けの最後の分が 1 秒延長される。
このフラグが設定されている限り、閏秒の挿入は毎日発生する。
-
-
STA_DEL (読み書き両用)
UTC 日付の最後の秒から閏秒を削除する 。
このフラグが設定されている限り、閏秒の削除は毎日発生する。
-
-
STA_UNSYNC (読み書き両用)
クロックを非同期状態にする。
-
-
STA_FREQHOLD (読み書き両用)
周波数を保持する。
通常、
ADJ_OFFSET
による調整では、減衰 (dampened) させながらの周波数調整が行われる。
これにより、1 回の呼び出しで現在のオフセットを補正するが、
長い期間のずれを修正するためには、少しずつ周波数調整を積み重ねて、
同じ方向へのオフセット調整が繰り返し行われる。
-
このフラグを使うと、
ADJ_OFFSET
の値を修正するときに、少しずつ周波数調整を行わない。
-
-
STA_PPSSIGNAL (読み出し専用)
有効な PPS 信号が存在する。
-
-
STA_PPSJITTER (読み出し専用)
PPS 信号のジッターが超過している。
-
-
STA_PPSWANDER (読み出し専用)
PPS 信号の wander が超過している。
-
-
STA_PPSERROR (読み出し専用)
PPS 信号の校正エラー。
-
-
STA_CLOCKERR (読み出し専用)
クロックハードウェア障害。
-
-
STA_NANO (読み出し専用。Linux 2.6.26 以降)
精度 (0 = マイクロ秒、1 = ナノ秒)。
ADJ_NANO
でセットし、
ADJ_MICRO
でクリアする。
-
-
STA_MODE (読み出し専用。Linux 2.6.26 以降)
モード (0 = Phase Locked Loop, 1 = Frequency Locked Loop)。
-
-
STA_CLK (読み出し専用。Linux 2.6.26 以降)
クロック源 (0 = A, 1 = B); 現在は使われていない。
status
の読み出し専用ビットを設定しようとした場合は黙って無視される。
clock_adjtime ()
(Linux 2.6.39 で追加された)
clock_adjtime()
システムコールは、
adjtimex()
の様に動作するが、動作させる対象の特定のクロックを指定する
clk_id
引き数を取る。
ntp_adjtime ()
(NTP "Kernel Application Program API", KAPI に記載されている)
ntp_adjtime()
ライブラリ関数は、
adjtimex()
と同じタスクを実行するための、より汎用的なインタフェースである。
以下の点以外は、
adjtimex()
と同じである:
- *
-
modes
に使われる定数は、プレフィックス "ADJ_" ではなく、
"MOD_" が使われており、同じサフィックスである (よって、
MOD_OFFSET,
MOD_FREQUENCY
などがある)。
また、以下のような例外がある。
- *
-
MOD_CLKA
は
ADJ_OFFSET_SINGLESHOT
と同じ意味である。
- *
-
MOD_CLKB
は
ADJ_TICK
と同じ意味である。
- *
-
KAPI に記載されていない
ADJ_OFFSET_SS_READ
は、同じ意味の定数はない。
返り値
成功した場合、
adjtimex()
と
ntp_adjtime()
は、クロックの状態、つまり、以下のいずれかの値を返す。
- TIME_OK
-
クロックが同期しており、閏秒の調整が保留されていない。
- TIME_INS
-
UTC 日付の最後に閏秒が挿入される。
- TIME_DEL
-
UTC 日付の最後から閏秒が削除される。
- TIME_OOP
-
閏秒の挿入が処理中である。
- TIME_WAIT
-
閏秒の挿入または削除が完了した。
この値は、次の
ADJ_STATUS
操作で
STA_INS
または
STA_DEL
フラグをクリアするまで、返される。
- TIME_ERROR
-
システムクロックが信頼できるサーバと同期できなかった。
この値は、以下のいずれかが真の場合、返される。
-
- *
-
STA_UNSYNC
または
STA_CLOCKERR
のいずれかが設定されている。
- *
-
STA_PPSSIGNAL
がクリアされ、かつ
STA_PPSFREQ
また
STA_PPSTIME
のいずれかが設定されている。
- *
-
STA_PPSTIME
と
STA_PPSJITTER
の両方が設定されている。
- *
-
STA_PPSFREQ
が設定され、かつ
STA_PPSWANDER
または
STA_PPSJITTER
のいずれかが設定されている。
-
シンボル名
TIME_BAD
は
TIME_ERROR
の同義語であり、過去互換性のために提供されている。
Linux 3.4 以降では、
呼び出し操作が非同期になったので、通常は、返り値が
呼び出し自体によって起きた状態変更を反映していない点に注意すること。
失敗した場合は
adjtimex()
と
ntp_adjtime()
は -1 を返し、
errno
が設定される。
エラー
- EFAULT
-
buf
が書き込み可能なメモリーを指していない。
-
-
EINVAL (カーネル Linux 2.6.26 以前)
buf.freq
の値を範囲 (-33554432, +33554432) の外に設定しようとした。
-
-
EINVAL (カーネル Linux 2.6.26 以前)
buf.offset
の値を許可された範囲外に設定しようとした。
カーネル Linux 2.0 以前では、許可された範囲は (-131072, +131072) である。
カーネル Linux 2.0 以降では、許可された範囲は (-512000, +512000) である。
- EINVAL
-
buf.status
の値を上記に記載した以外に設定しようとした。
- EINVAL
-
clock_adjtime()
に指定された
clk_id
が、以下の 2 つのいずれかの理由で不正である。
System-V 形式のハードコードされた
正のクロック ID の値が範囲外である。
または、動的な
clk_id
がクロックオブジェクトの有効なインスタンスを参照していない。
動的なクロックについての議論は、
clock_gettime(2)
を参照すること。
- EINVAL
-
buf.tick
に
900000/HZ
から
1100000/HZ
の範囲外の値を設定しようとした。
ここで
HZ
はシステムのタイマー割り込みの周期である。
- ENODEV
-
動的な
clk_id
で表された (例えば、USB のような) ホットプラグデバイスが、
キャラクターデバイスがオープンされた後で消えた。
動的なクロックについての議論は、
clock_gettime(2)
を参照すること。
- EOPNOTSUPP
-
指定された
clk_id
が調整をサポートしていない。
- EPERM
-
buf.modes
が 0 でも
ADJ_OFFSET_SS_READ
でもなく、かつ呼び出し元が十分な特権を持っていない。
Linux では
CAP_SYS_TIME
ケーパビリティが必要である。
属性
このセクションで使われる用語の説明は、
attributes(7)
を参照すること。
| インタフェース | 属性 | 値
|
|
ntp_adjtime()
| スレッドセーフ性 | MT セーフ
|
準拠
これらのインタフェースは POSIX.1 に記載されていない。
adjtimex()
と
clock_adjtime()
は、Linux 特有であり、移植を意図したプログラムで使用すべきではない。
NTP デーモンで使うべき API は
ntp_adjtime()
である。
注意
構造体
timex
では、
freq,
ppsfreq,
stabil
は小数部が 16 ビットの ppm (parts per million) である。
つまり、これらのフィールドの値 1 は 2^-16 ppm で、2^16=65536 が 1 ppm である。
入力
(freq
の場合) でも出力でもこの通りである。
STA_INS
と
STA_DEL
をトリガーとして行われる閏秒の処理は、
カーネルによってタイマーコンテクストで行われる。
よって、挿入または削除される閏秒には、1 tick かかる。
関連項目
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"
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.07 の一部である。
プロジェクトの説明、バグ報告に関する情報、このページの最新版は、
http://www.kernel.org/doc/man-pages/ に書かれている。
Index
- 名前
-
- 書式
-
- 説明
-
- clock_adjtime ()
-
- ntp_adjtime ()
-
- 返り値
-
- エラー
-
- 属性
-
- 準拠
-
- 注意
-
- 関連項目
-
- この文書について
-
This document was created by
man2html,
using the manual pages.
Time: 14:23:47 GMT, January 01, 2021