NTP_ADJTIME(2)

FreeBSD System Calls Manual

NTP_ADJTIME(2)

名称

ntp_adjtime, ntp_gettime — Network Time Protocol (ネットワークタイムプロトコル) (NTP) デーモンインタフェースシステムコール

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/timex.h>

int
ntp_adjtime( struct timex *);

int
ntp_gettime( struct ntptimeval *);

解説

2 のシステムコール ntp_adjtime() と ntp_gettime() は、Network Time Protocol (ネットワークタイムプロトコル) (NTP) デーモン ntpd(8) のカーネルインタフェースです。

ntp_adjtime() 関数は、外部的に配信されている時刻にシステムクロックを調整するための NTP デーモンによって使用されます。時刻のオフセットと ntp_adjtime() によって設定される関連する変数は、システムクロックを制御するフェーズロックループまたは周波数ロックループの (それぞれ、PLL と FLL) フェーズと周波数を調整するために hardclock() によって使用されます。

ntp_gettime() 関数は、時間、最大誤差 (シンク距離) と推定誤差 (分散) をクライアントのユーザアプリケーションプログラムに提供します。

次において、PPS を参照するすべての変数は、 PPS_SYNC オプションがカーネルで有効にされる場合のみ、関連しています。

ntp_adjtime() には、引数として次の形式の struct timex * があります:

struct timex { 
 unsigned int modes; /* クロックモードビット (wo) */ 
 long offset;  /* 時刻オフセット (us) (rw) */ 
 long freq;  /* 周波数オフセット (ppm 単位) (rw) */ 
 long maxerror;  /* 最大誤差 (us) (rw) */ 
 long esterror;  /* 推定誤差 (us) (rw) */ 
 int status;  /* クロック状態ビット (rw) */ 
 long constant;  /* pll 時刻定数 (rw) */ 
 long precision;  /* 時刻精度 (us) (ro) */ 
 long tolerance;  /* クロック周波数許容誤差 (ppm 単位) 
     * (ro) */ 
 /* 
         * 次の読み込み専用の構造体のメンバは、PPS シグナル制御規則が 
         * カーネルで設定される場合にだけ、実装されされます. 
  */ 
 long ppsfreq;  /* pps 周波数 (ppm 単位) (ro) */ 
 long jitter;  /* pps ジッタ (us) (ro) */ 
 int shift;  /* インターバル存続期間 (s) (shift) (ro) */ 
 long stabil;  /* pps 安定性 (ppm 単位) (ro) */ 
 long jitcnt;  /* 超過したジッタ制限 (ro) */ 
 long calcnt;  /* 測定インターバル (ro) */ 
 long errcnt;  /* 測定誤差 (ro) */ 
 long stbcnt;  /* 超過した安定性制限 (ro) */ 
};

ntp_adjtime() に引数として使用されるとき、この構造体のメンバには、次の意味があります:

modes

現在の ntp_adjtime() 呼び出しでどんな設定が変更されるべきであるかを定義します (書き込み専用)。次をビット単位の OR したものです:

offset

少しの増分でシステム時間を調整するために PLL/FLL によって使用される (マイクロ秒単位の) 時刻オフセット (読み込み専用)。

freq

周波数オフセット (ppm 単位) (読み込み、書き込み)。

maxerror

(マイクロ秒単位の) 最大誤差。 ntp_adjtime() 呼び出しで初期化され、最大誤差の限界の増加を反映するために 1 秒毎に 1 度カーネルによって増加されます (読み込み、書き込み)。

esterror

(マイクロ秒単位の) 推定誤差。 ntp_adjtime() によって設定され読み込まれますが、カーネルでは使用されません (読み込み、書き込み)。

status

システムクロック状態ビット (読み込み、書き込み)。次をビット単位の OR したものです:

constant

PLL 時刻定数、帯域幅の決定、または PLL の“stiffness” (堅固さ) (読み込み専用)。

precision

(マイクロ秒単位の) クロック精度。ほとんどの場合、カーネルチック (tick) 変数と同じです ( hz(9) 参照)。精度クロックカウンタ、または外部の時刻保持シグナルが利用可能であるなら、それは、はるかに小さいかもしれません (そして、シグナルの状態に依存しています) (読み込み専用)。

tolerance

最大周波数の誤差、または CPU クロック発振器の許容誤差 (ppm 単位)。通常、アーキテクチャのプロパティですが、外部の時刻保持シグナルの影響を受けて変化するかもしれません。

ppsfreq

周波数の中央フィルタによって作成される PPS 周波数オフセット (ppm 単位)(読み込み専用)。

jitter

マイクロ秒単位の中央のフィルタによって測定される PPS ジッタ (jitter) (書き込み禁止)。

shift

秒単位のインターバル存続期間の 2 を底とする対数 (PPS, 読み込み専用)。

stabil

PPS の安定性 (ppm 単位)。周波数中央フィルタによって測定される分散 (ワンダ (wander)) (読み込み専用)。

jitcnt

ジッタ (jitter) が、制限 MAXTIME を超えた時刻中央フィルタによって測定されるので、破棄された秒数 (PPS, 読み込み専用)。

calcnt

測定インターバルのカウント (PPS, 読み込み専用)。

errcnt

ワンダ (wander) が制限 MAXFREQ を超えるか、または測定インターバルジッタ (jitter) が 2 つのチック (tick) を超えるところで、破棄された測定インターバルの数 (PPS, 読み込み専用)。

stbcnt

周波数ワンダ (wander) が、制限 MAXFREQ/4 を超えるので、廃棄された測定インターバルの数 (PPS, 読み込み専用)。

ntp_adjtime() 呼び出しの後に、 struct timex * 構造体は、対応する変数の現在の値を含んでいます。

ntp_gettime() には、引数として次のメンバがある struct ntptimeval * があります:

struct ntptimeval { 
 struct timeval time; /* 現在の時刻 (ro) */ 
 long maxerror;  /* 最大誤差 (us) (ro) */ 
 long esterror;  /* 推測誤差 (us) (ro) */ 
};

これらには、次の意味があります:

戻り値

ntp_adjtime() と ntp_gettime() は、成功すれば、クロックの現在の状態を返すか、または copyin(9) と copyout(9) のいずれかのエラーを返します。さらに、 ntp_adjtime() を呼び出すユーザに十分なパーミッションがないなら、 ntp_adjtime() は、 EPERM を返します。

クロックのあり得る状態は、次の通りです:

エラー

ntp_adjtime() システムコールは、呼び出し側に十分なパーミッションがないなら、 EPERM を返します。

バグ

この API は、非常に複雑で、ステートフルであることに注意してください。最初に ntpd(8) ソースを徹底的に調査しないで、ユーザは変更を試みるべきではありません。

July 13, 2005

FreeBSD

YOS OPENSONAR

名称

ライブラリ

書式

解説

戻り値

エラー

関連項目

バグ