adjtimex

Section: System Calls (2)
Updated: 2026-02-08
Index JM Home Page

名前

adjtimex, clock_adjtime, ntp_adjtime - カーネルの時計を調整する

ライブラリ

標準 C ライブラリ (libc, -lc)

書式

#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;      /* 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 */ };

modes フィールドは (必要に応じて) どのパラメータを設定するか決定します。(このページの後半で説明するように、ntp_adjtime()に使用される定数は同等ですが、名前が異なります。) 以下のビットの 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;パルス/秒)周波数制御を有効にします。
STA_PPSTIME (読み書き両用): PPS time discipline を有効にします。
STA_FLL (読み書き両用): Frequency Locked Loop (FLL) モードを選択します。
STA_INS (読み書き両用): UTC 日の最後の1 秒の後に閏秒を挿入します。これにより、その日の最後の 1分が 1秒延長されます。このフラグが設定されている限り、閏秒の挿入は毎日行われます。
STA_DEL (読み書き両用): UTC 日の最後の 1秒でうるう秒を削除します。このフラグが設定されている限り、うるう秒の削除は毎日行われます。
STA_UNSYNC (読み書き両用): クロックを非同期状態にします。
STA_FREQHOLD (読み書き両用): 保持周波数。通常、ADJ_OFFSET を介して行われる調整は、減衰された周波数調整も行われます。したがって、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 ()

clock_adjtime() システムコール(Linux 2.6.39で追加された)は、adjtimex()と同じように動作しますが、clk_id 引数を追加して特定のクロックを指定します。

ntp_adjtime ()

ntp_adjtime() ライブラリ関数(NTPAPIと同じタスクを実行するためのより移植性の高いインタフェースです。次の点を除き、adjtimex() と同じです。

•: modes で使用される定数には、という接頭語が付き、同じ接尾語が付いています(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 以降では、この関数は非同期に動作し、戻り値は通常この関数自身による状態変化を反映しないことに注意してください。

失敗した場合、これらのシステムコールは -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()	Thread safety	MT-Safe

標準

adjtimex(): clock_adjtime() Linux.

NTP デーモンの優先 API は ntp_adjtime() です。

注意

構造体 timex , freq, ppsfreq, stabil では、小数部が 16 ビットの ppm (parts per million) です。つまり、これらのフィールドの値 1 は 2ha-16 ppm で、 2ha16=65536 が 1 ppm である。入力 (freq の場合) でも出力でもこの通りです。

STA_INS と STA_DEL によってトリガーされた閏秒の処理は、タイマーのコンテキストでカーネルによって行われます。したがって、閏秒が挿入または削除されるには、秒に 1ティックが必要です。