NTP_ADJTIME(2) | FreeBSD System Calls Manual | NTP_ADJTIME(2) |
名称
ntp_adjtime, ntp_gettime — Network Time Protocol (ネットワークタイムプロトコル) (NTP) デーモンインタフェースシステムコールライブラリ
Standard C Library (libc, -lc)解説
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 |