EN JA
NTP_ADJTIME(2)
NTP_ADJTIME(2) FreeBSD System Calls Manual NTP_ADJTIME(2)

名称

ntp_adjtime, ntp_gettimeNetwork 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 したものです:
MOD_OFFSET
時刻オフセットを設定します
MOD_FREQUENCY
周波数オフセットを設定します
MOD_MAXERROR
最大時刻誤差を設定する
MOD_ESTERROR
推定された時刻誤差を設定します
MOD_STATUS
クロックステータスビットを設定します
MOD_TIMECONST
PLL 時刻定数を設定します
MOD_CLKA
クロック A を設定します
MOD_CLKB
クロック B を設定します
offset
少しの増分でシステム時間を調整するために PLL/FLL によって使用される (マイクロ秒単位の) 時刻オフセット (読み込み専用)。
freq
周波数オフセット (ppm 単位) (読み込み、書き込み)。
maxerror
(マイクロ秒単位の) 最大誤差。 ntp_adjtime() 呼び出しで初期化され、最大誤差の限界の増加を反映するために 1 秒毎に 1 度カーネルによって増加されます (読み込み、書き込み)。
esterror
(マイクロ秒単位の) 推定誤差。 ntp_adjtime() によって設定され読み込まれますが、カーネルでは使用されません (読み込み、書き込み)。
status
システムクロック状態ビット (読み込み、書き込み)。次をビット単位の OR したものです:
STA_PLL
PLL 更新を有効にします (読み込み、書き込み)。
STA_PPSFREQ
PPS 周波数制御規則を有効にします (読み込み、書き込み)。
STA_PPSTIME
PPS 時刻制御規則を有効にします (読み込み、書き込み)。
STA_FLL
周波数ロックモードを選択します (読み込み、書き込み)。
STA_INS
リープ (leap) 挿入します (読み込み、書き込み)。
STA_DEL
リープ (leap) 削除します (読み込み、書き込み)。
STA_UNSYNC
クロック非同期 (読み込み、書き込み)。
STA_FREQHOLD
保持周波数 (読み込み、書き込み)。
STA_PPSSIGNAL
PPS シグナル存在 (読み込み専用)。
STA_PPSJITTER
PPS 超過したシグナルジッタ (読み込み専用)。
STA_PPSWANDER
PPS 超過したシグナルワンダ (wander) (読み込み専用)。
STA_PPSERROR
PPS シグナル測定誤差 (読み込み専用)。
STA_CLOCKERR
クロックハードウェア障害 (読み込み専用)。
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) */ 
};

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

time
現在の時刻 (読み込み専用)。
maxerror
マイクロ秒単位の最大誤差 (読み込み専用)。
esterror
マイクロ秒単位の推定誤差 (読み込み専用)。

戻り値

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

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

TIME_OK
すべてオッケー、リープ (閏) 秒の警告はありません。
TIME_INS
“insert leap second” (リープ (閏) 秒を挿入) の警告。最終的には、リープ (閏) 秒は 23:59:59 の後に挿入されます。
TIME_DEL
“delete leap second” (リープ (閏) 秒を削除) の警告。最終的には、2 番目の 23:59:59 はスキップされます。
TIME_OOP
進行中のリープ (閏) 秒。
TIME_WAIT
リープ (閏) 秒は、最後の数秒以内に起こった。
TIME_ERROR
クロックは同期しません。

エラー

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

関連項目

options(4), ntpd(8), hardclock(9), hz(9)
http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
http://www.boulder.nist.gov/timefreq/general/faq.htm
ftp://time.nist.gov/pub/leap-seconds.list

バグ

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