Scroll to navigation

ADJTIMEX(2) Linux Programmer's Manual ADJTIMEX(2)

名前

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

書式

#define _BSD_SOURCE      /* feature_test_macros(7) 参照 */
#include <sys/timex.h>
int adjtimex(struct timex *buf);

説明

Linux は David L. Mill の時計調節アルゴリズムを使用している (RFC 5905 を参照)。 システムコール adjtimex() はこのアルゴリズムの調節のパラメーターを読み取ったり、設定したりする。 この関数は timex 構造体へのポインターを受け取り、その値でカーネルのパラメーターを更新して、 同じ構造体に現在のカーネルの値を返す。 この構造体は以下のように宣言される:


struct timex {


    int  modes;      /* モードの選択 */


    long offset;     /* 時刻オフセット; STA_NANO ステータスフラグが


                        設定されるとナノ秒で、それ以外はマイクロ秒 */


    long freq;       /* 周波数オフセット。 単位は 2^-16 ppm


                        (parts per million)。 「注意」を参照 */


    long maxerror;   /* 最大エラー (マイクロ秒) */


    long esterror;   /* 推定エラー (マイクロ秒) */


    int  status;     /* クロックコマンド/ステータス */


    long constant;   /* PLL (phase-locked loop) 時刻定数 */


    long precision;  /* クロック精度 (マイクロ秒、読み出し専用) */


    long tolerance;  /* クロック周波数耐性 (ppm、読み出し専用) */


    struct timeval time;


                     /* 現在時刻 (読み出し専用、 ADJ_SETOFFSET の


                        場合以外); リターン時は time.tv_usec は


                        STA_NANO ステータスフラグが設定されると


                        ナノ秒で、それ以外はマイクロ秒 */


    long tick;       /* クロック tick 間のマイクロ秒 */


    long ppsfreq;    /* PPS (pulse per second) 周波数 (単位は


                        2^-16 ppm、「注意」を参照、読み出し専用) */


    long jitter;     /* PPS ジッター (読み出し専用); STA_NANO


                        ステータスフラグが設定されるとナノ秒、


                        それ以外はマイクロ秒 */


    int  shift;      /* PPS interval duration (秒、読み出し専用) */


    long stabil;     /* PPS 安定性 (2^-16 ppm、「注意」を参照、


                        読み出し専用) */


    long jitcnt;     /* PPS ジッター上限超過 (読み出し専用) */


    long calcnt;     /* PPS 校正間隔 (読み出し専用) */


    long errcnt;     /* PPS 校正エラー (読み出し専用) */


    long stbcnt;     /* PPS 安定性上限超過 (読み出し専用) */


    int tai;         /* TAI オフセット、直前の ADJ_TAI 命令で設定


                        したもの (秒、読み出し専用、


                        Linux 2.6.26 以降) */


    /* これ以降のパディングバイトは将来の拡張用である */
};

modes フィールドは (必要に応じて) どのパラメーターを設定するか決定する。 以下のビット値の 0 個以上の ビット OR からなるビットマスクである。

buf.offset を時刻オフセットを設定する。
buf.freq を周波数オフセットを設定する。
buf.maxerror を最大時刻エラーを設定する。
buf.esterror を推定時刻エラー (estimated time error) を設定する。
buf.status をクロックステータスを設定する。
buf.constant を PLL の時刻定数を設定する。 (下記の) STA_NANO ステータスフラグがクリアされた場合、 カーネルはこの値に 4 を足す。
buf.time を現在時刻に加算する。 buf.status に ADJ_NANO フラグが指定された場合、 buf.time.tv_usec はナノ秒として解釈される。 そうでない場合はマイクロ秒として解釈される。
マイクロ秒単位の精度を選択する。
ナノ秒単位の精度を選択する。 ADJ_MICRO と ADJ_NANO の一方のみを指定すること。
buf->constant を TAI (Atomic International Time) オフセットを設定する。

ADJ_TAI は ADJ_TIMECONST と組み合わせて使わないこと。 ADJ_TIMECONST も buf->constant フィールド利用するからである。

TAI の詳細な説明および TAI と UTC の違いについては BIPM を参照。

buf.tick を tick 値に設定する。

上記の代わりに、 modes に以下の値 (複数ビットのマスク) のいずれかを指定することもできる。 この場合は他のビットは modes に指定すべきではない。

古い形式の adjtime(): 時刻を buf.offset で指定された値で (徐々に) 調整する。 buf.offset はマイクロ秒単位の調整値である。
ADJ_OFFSET_SINGLESHOT 操作を行った後でまだ残っている調整すべき時刻量を (buf.offset で) 返す。 この機能は Linux 2.6.24 で追加されたが、 Linux 2.6.28 までは正常に動作しなかった。

通常のユーザーは modes の値は 0 か ADJ_OFFSET_SS_READ のいずれかに制限されている。 スーパーユーザーのみが全てのパラメーターを設定できる。

buf.status フィールドはビットマスクで、 このフィールドを使って NTP 実装に関連するステータスビットの設定や取得を行うことができる。 マスクのビットのいくつかは読み書き両用で、 他のビットは読み出し専用である。

Phase Locked Loop (PLL) の更新を有効にする (読み書き両用)。 ADJ_OFFSET 経由で設定できる。
PPS freq discipline を有効にする (読み書き両用)
PPS time discipline を有効にする (読み書き両用)
Frequency Locked Loop (FLL) モードを選択する (読み書き両用)
閏秒を挿入する (読み書き両用)
閏秒を削除する (読み書き両用)
クロックを非同期状態にする (読み書き両用)
周波数を保持する (読み書き両用)
PPS 信号が存在する (読み出し専用)
PPS 信号のジッターが超過している (読み出し専用)
PPS 信号の wander が超過している (読み出し専用)
PPS 信号の校正エラー (読み出し専用)
クロックハードウェア障害 (読み出し専用)
精度 (0 = マイクロ秒、 1 = ナノ秒; 読み出し専用)。 ADJ_NANO でセットし、 ADJ_MICRO でクリアする。
モード (0 = Phase Locked Loop, 1 = Frequency Locked Loop; 読み出し専用)
クロック源 (0 = A, 1 = B; 読み出し専用)

status の読み出し専用ビットを設定しようとした場合は黙って無視される。

返り値

成功した場合、 adjtimex() は クロックの状態、つまり、以下のいずれかの値を返す。

クロックが同期している。
閏秒を挿入した。
閏秒を削除した。
閏秒が処理中である。
閏秒が発生した。
クロックが同期していない。 シンボル名 TIME_BAD は TIME_ERROR の同義語であり、 過去互換性のために提供されている。

失敗した場合は adjtimex() は -1 を返し、 errno が設定される。

エラー

buf が書き込み可能なメモリーを指していない。
buf.offset へ -131071 〜 +131071 の範囲以外の値を設定しようとしたか、 buf.status に上記以外の値を設定しようとしたか、 buf.tick に 900000/HZ 〜 1100000/HZ の範囲以外の値を設定しようとした。 ここで HZ はシステムのタイマー割り込みの周期である。
buf.modes が 0 でも ADJ_OFFSET_SS_READ でもなく、かつ呼び出し元が十分な特権を持っていない。 Linux では CAP_SYS_TIME ケーパビリティが必要である。

注意

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

準拠

adjtimex() は Linux 特有であり、 移植を意図したプログラムで使用すべきではない。 システムクロックを調整する方法で、 移植性があるが自由度は劣る方法については adjtime(3) を参照のこと。

関連項目

settimeofday(2), adjtime(3), capabilities(7), time(7), adjtimex(8)

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。

2014-12-31 Linux