[要約] RFC 2783は、UNIXライクなオペレーティングシステムのための1.0バージョンの秒パルスAPIに関する要約です。このRFCの目的は、正確な時刻同期を提供するために秒パルス信号を使用する方法を定義することです。
Network Working Group J. Mogul
Request for Comments: 2783 Compaq WRL
Category: Informational D. Mills
University of Delaware
J. Brittenson
Sun
J. Stone
Stanford
U. Windl
Universitaet Regensburg
March 2000
Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0
Unixのようなオペレーティングシステム用の秒単位API、バージョン1.0
Status of this Memo
本文書の位置付け
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
このメモは、インターネットコミュニティに情報を提供します。いかなる種類のインターネット標準を指定しません。このメモの配布は無制限です。
Copyright Notice
著作権表示
Copyright (C) The Internet Society (2000). All Rights Reserved.
Copyright（c）The Internet Society（2000）。無断転載を禁じます。
Abstract
概要
RFC 1589 describes a UNIX kernel implementation model for high-precision time-keeping. This model is meant for use in conjunction with the Network Time Protocol (NTP, RFC 1305), or similar time synchronization protocols. One aspect of this model is an accurate interface to the high-accuracy, one pulse-per-second (PPS) output typically available from precise time sources (such as a GPS or GOES receiver). RFC 1589 did not define an API for managing the PPS facility, leaving implementors without a portable means for using PPS sources. This document specifies such an API.
RFC 1589は、高精度の時間維持のためのUNIXカーネル実装モデルについて説明しています。このモデルは、ネットワークタイムプロトコル（NTP、RFC 1305）または同様の時間同期プロトコルと組み合わせて使用することを目的としています。このモデルの1つの側面は、正確な時間ソース（GPSやGoes Receiverなど）から通常入手可能な、高精度の正確なインターフェースです。RFC 1589は、PPS施設を管理するためのAPIを定義せず、PPSソースを使用するためのポータブルな手段なしに実装者を残しました。このドキュメントは、このようなAPIを指定します。
Table of Contents
目次
1 Introduction................................................... 2
2 Data types for representing timestamps......................... 4
2.1 Resolution................................................... 4
2.2 Time scale................................................... 5
3 API............................................................ 5
3.1 PPS abstraction.............................................. 6
3.2 New data structures.......................................... 7
3.3 Mode bit definitions......................................... 10
3.4 New functions................................................ 12
3.4.1 New functions: obtaining PPS sources....................... 13
3.4.2 New functions: setting PPS parameters...................... 14
3.4.3 New functions: access to PPS timestamps.................... 16
3.4.4 New functions: disciplining the kernel timebase............ 18
3.5 Compliance rules............................................. 20
3.5.1 Functions.................................................. 20
3.5.2 Mode bits.................................................. 20
3.6 Examples..................................................... 21
4 Security Considerations........................................ 24
5 Acknowledgements............................................... 24
6 References..................................................... 25
7 Authors' Addresses............................................. 26
A. Extensions and related APIs................................... 27
A.1 Extension: Parameters for the "echo" mechanism............... 27
A.2 Extension: Obtaining information about external clocks....... 27
A.3 Extension: Finding a PPS source.............................. 28
B. Example implementation: PPSDISC Line discipline............... 29
B.1 Example...................................................... 29
C. Available implementations..................................... 30
Full Copyright Statement......................................... 31
1 Introduction
1はじめに
RFC 1589 [4] describes a model and programming interface for generic operating system software that manages the system clock and timer functions. The model provides improved accuracy and stability for most workstations and servers using the Network Time Protocol (NTP) [3] or similar time synchronization protocol. The model supports the use of external timing sources, such as the precision pulse-per-second (PPS) signals typically available from precise time sources (such as a GPS or GOES receiver).
RFC 1589 [4]は、システムクロックとタイマー機能を管理する一般的なオペレーティングシステムソフトウェアのモデルとプログラミングインターフェイスについて説明しています。このモデルは、ネットワークタイムプロトコル（NTP）[3]または同様の時間同期プロトコルを使用して、ほとんどのワークステーションとサーバーの精度と安定性の向上を提供します。このモデルは、通常、正確な時間ソース（GPSやGoesレシーバーなど）から利用可能な秒単位（PPS）シグナルなどの外部タイミングソースの使用をサポートしています。
However, RFC 1589 did not define an application programming interface (API) for the PPS facility. This document specifies such an interface, for use with UNIX (or UNIX-like) operating systems. Such systems often conform to the "Single UNIX Specification" [5], sometimes known as POSIX.
ただし、RFC 1589は、PPS施設のアプリケーションプログラミングインターフェイス（API）を定義しませんでした。このドキュメントは、UNIX（またはUNIXのような）オペレーティングシステムで使用するために、このようなインターフェイスを指定します。このようなシステムは、しばしば「単一のUnix仕様」[5]に適合し、Posixとして知られています。
One convenient means to provide a PPS signal to a computer system is to connect that signal to a modem-control pin on a serial-line interface to the computer. The Data Carrier Detect (DCD) pin is frequently used for this purpose. Typically, the time-code output of the time source is transmitted to the computer over the same serial line. The computer detects a signal transition on the DCD pin, usually by receiving an interrupt, and records a timestamp as soon as possible.
コンピューターシステムにPPS信号を提供する便利な手段の1つは、その信号をシリアルラインインターフェイスのモデム制御ピンにコンピューターに接続することです。データキャリア検出（DCD）ピンは、この目的に頻繁に使用されます。通常、時間ソースのタイムコード出力は、同じシリアルラインでコンピューターに送信されます。コンピューターは、通常は割り込みを受信してDCDピンの信号遷移を検出し、できるだけ早くタイムスタンプを記録します。
Although existing practice has focussed on the use of serial lines and DCD transitions, PPS signals might also be delivered by other kinds of devices. The API specified in this document does not require the use of a serial line, although it may be somewhat biased in that direction.
既存の慣行は、シリアルラインとDCD遷移の使用に焦点を当てていますが、PPS信号は他の種類のデバイスによっても配信される場合があります。このドキュメントで指定されたAPIは、シリアルラインの使用を必要としませんが、その方向に多少偏っている可能性があります。
The typical use of this facility is for the operating system to record ("capture") a high-resolution timestamp as soon as possible after it detects a PPS signal transition (usually indicated by an interrupt). This timestamp can then be made available, with less stringent delay constraints, to time-related software. The software can compare the captured timestamp to the received time-code to accurately discover the offset between the system clock and the precise time source.
この施設の典型的な使用は、オペレーティングシステムがPPS信号遷移を検出した後、できるだけ早く高解像度のタイムスタンプを記録する（「キャプチャ」）することです（通常は割り込みで示されます）。このタイムスタンプは、時間関連ソフトウェアに対して、より厳しい遅延制約で利用可能にすることができます。ソフトウェアは、キャプチャされたタイムスタンプを受信したタイムコードと比較して、システムクロックと正確な時間源の間のオフセットを正確に発見できます。
The operating system may also deliver the PPS event to a kernel procedure, called the "in-kernel PPS consumer." One example would be the "hardpps()" procedure, described in RFC 1589, which is used to discipline the kernel's internal timebase.
また、オペレーティングシステムは、「型PPS消費者」と呼ばれるカーネル手順にPPSイベントを提供する場合があります。1つの例は、カーネルの内部タイムベースを懲戒するために使用されるRFC 1589で説明されている「hardpps（）」手順です。
The API specified in this document allows for one or more signal sources attached to a computer system to provide PPS inputs, at the option of user-level software. User-level software may obtain signal-transition timestamps for any of these PPS sources. User-level software may optionally specify at most one of these PPS sources to be used to discipline the system's internal timebase.
このドキュメントで指定されたAPIは、ユーザーレベルのソフトウェアのオプションで、コンピューターシステムに接続された1つ以上の信号ソースをコンピューターシステムに添付して、PPS入力を提供できるようにします。ユーザーレベルのソフトウェアは、これらのPPSソースのいずれかの信号移動タイムスタンプを取得する場合があります。ユーザーレベルのソフトウェアは、システムの内部タイムベースを懲戒するために使用するこれらのPPSソースのせいぜい1つをオプションで指定する場合があります。
Although the primary purpose of this API is for capturing true pulse-per-second events, the API may also be used for accurately timestamping events of other periods, or even aperiodic events, when these can be expressed as signal transitions.
このAPIの主な目的は、秒単位の真のパルスイベントをキャプチャすることですが、APIは、これらを信号遷移として表現できる場合、他の期間、または非周期イベントのイベントを正確にタイムスタンプするためにも使用できます。
This document does not define internal details of how the API must be implemented, and does not specify constraints on the accuracy, resolution, or latency of the PPS feature. However, the utility of this feature is inversely proportional to the delay (and variance of delay), and implementors are encouraged to take this seriously.
このドキュメントは、APIの実装方法の内部詳細を定義するものではなく、PPS機能の精度、解像度、またはレイテンシに関する制約を指定しません。ただし、この機能の有用性は、遅延（および遅延の分散）に反比例するものであり、実装者はこれを真剣に受け止めることが奨励されています。
In principle, the rate of events to be captured, or the frequency of the signals, can range from once per day (or less often) to several thousand per second. However, since in most implementations the timestamping function will be implemented as a processor interrupt at a relatively high priority, it is prudent to limit the rate of such events. This may be done either by mechanisms in the hardware that generates the signals, or by the operating system.
原則として、キャプチャされるイベントの速度、または信号の頻度は、1日1回（または頻繁に）から1秒あたり数千の範囲です。ただし、ほとんどの実装では、タイムスタンプ機能は比較的優先度の高いプロセッサ割り込みとして実装されるため、このようなイベントのレートを制限することは賢明です。これは、信号を生成するハードウェア内のメカニズム、またはオペレーティングシステムによって行われる場合があります。
2 Data types for representing timestamps
タイムスタンプを表すための2つのデータ型
Computer systems use various representations of time. Because this API is concerned with the provision of high-accuracy, high-resolution time information, the choice of representation is significant. (Here we consider only binary representations, not human-format representations.)
コンピューターシステムは、時間のさまざまな表現を使用しています。このAPIは、高精度の高解像度時間情報の提供に関係しているため、表現の選択は重要です。（ここでは、バイナリ表現のみを検討し、人間の形式の表現ではありません。）
The two interesting questions are:
2つの興味深い質問は次のとおりです。
1. what is the resolution of the representation?
1. 表現の解像度は何ですか？
2. what time scale is represented?
2. どの時間スケールが表されますか？
These questions often lead to contentious arguments. Since this API is intended for use with NTP and POSIX-compliant systems, however, we can limit the choices to representations compatible with existing NTP and POSIX practice, even if that practice is considered "wrong" in some quarters.
これらの質問はしばしば論争のある議論につながります。ただし、このAPIはNTPおよびPOSIXに準拠したシステムで使用することを目的としているため、一部の四半期でそのプラクティスが「間違っている」と見なされていても、既存のNTPおよびPOSIXプラクティスと互換性のある表現に選択肢を制限できます。
In the NTP protocol, "timestamps are represented as a 64-bit unsigned fixed-point number, in seconds relative to 0h on 1 January 1900. The integer part is in the first 32 bits and the fraction part in the last 32 bits [...] The precision of this representation is about 200 picoseconds" [3].
NTPプロトコルでは、「タイムスタンプは、1900年1月1日の0Hに比べて秒単位で64ビットの符号なしの固定点数として表されます。整数部は最初の32ビットと最後の32ビットの分数部分です[。..]この表現の精度は約200ピコ秒です」[3]。
However, most computer systems cannot measure time to this resolution (this represents a clock rate of 5 GHz). The POSIX gettimeofday() function returns a "struct timeval" value, with a resolution of 1 microsecond. The POSIX clock_gettime() function returns a "struct timespec" value, with a resolution of 1 nanosecond.
ただし、ほとんどのコンピューターシステムは、この解像度までの時間を測定することはできません（これは5 GHzのクロックレートを表します）。POSIX getTimeOfDay（）関数は、解像度が1マイクロ秒の「struct timeval」値を返します。posix clock_gettime（）関数は、解像度が1ナノ秒の「struct timespec」値を返します。
This API uses an extensible representation, but defaults to the "struct timespec" representation.
このAPIは拡張可能な表現を使用しますが、デフォルトは「struct timespec」表現になります。
Several different time scales have been proposed for use in computer systems. UTC and TAI are the two obvious candidates.
コンピューターシステムで使用するために、いくつかの異なる時間スケールが提案されています。UTCとTAIは2つの明らかな候補者です。
Some people would prefer the use of TAI, which is identical to UTC except that it does not correct for leap seconds. Their preference for TAI stems from the difficulty of computing precise time differences when leap seconds are involved, especially when using times in the future (for which the exact number of leap seconds is, in general, unknowable).
一部の人々は、Leap scondsを修正しないことを除いて、UTCと同一のTAIの使用を好むでしょう。TAIに対する彼らの好みは、特に将来の時間を使用する場合（一般的には、一般的にはわからない）、LEAP秒が関係する場合、正確な時間の違いを計算することの難しさに由来します。
However, POSIX and NTP both use UTC, albeit with different base dates. Given that support for TAI would, in general, require other changes to the POSIX specification, this API uses the POSIX base date of 00:00 January 1, 1970 UTC, and conforms to the POSIX use of the UTC time scale.
ただし、POSIXとNTPはどちらも、異なる基本日付がありますが、UTCを使用しています。一般に、TAIのサポートにはPOSIX仕様の他の変更が必要であることを考えると、このAPIは1970年1月1日00:00のPOSIXベースの日付を使用し、UTC時間スケールのPOSIX使用に準拠しています。
3 API
3 API
A PPS facility can be used in two different ways:
PPS施設は、2つの異なる方法で使用できます。
1. An application can obtain a timestamp, using the system's internal timebase, for the most recent PPS event.
1. 最新のPPSイベントに対して、システムの内部タイムベースを使用して、アプリケーションを取得できます。
2. The kernel may directly utilize PPS events to discipline its internal timebase, thereby providing highly accurate time to all applications.
2. カーネルは、PPSイベントを直接利用して内部タイムベースを懲戒し、それによりすべてのアプリケーションに非常に正確な時間を提供する場合があります。
This API supports both uses, individually or in combination. The timestamping feature may be used on any number of PPS sources simultaneously; the timebase-disciplining feature may be used with at most one PPS source.
このAPIは、個別または組み合わせの両方の使用をサポートします。タイムスタンプ機能は、任意の数のPPSソースで同時に使用できます。TimeBase Disciplinging機能は、最大1つのPPSソースで使用できます。
Although the proper implementation of this API requires support from the kernel of a UNIX system, this document defines the API in terms of a set of library routines. This gives the implementor some freedom to divide the effort between kernel code and library code (different divisions might be appropriate on microkernels and monolithic kernels, for example).
このAPIの適切な実装には、UNIXシステムのカーネルからのサポートが必要ですが、このドキュメントでは、ライブラリルーチンのセットでAPIを定義しています。これにより、実装者は、カーネルコードとライブラリコードの間で取り組みを自由に分割することができます（たとえば、マイクロカーネルとモノリシックカーネルでは異なる部門が適切かもしれません）。
A PPS signal consists of a series of pulses, each with an "asserted" (logical true) phase, and a "clear" (logical false) phase. The two phases may be of different lengths. The API may capture an "assert timestamp" at the moment of the transition into the asserted phase, and a "clear timestamp" at the moment of the transition into the clear phase.
PPS信号は一連のパルスで構成され、それぞれに「アサートされた」（論理的な真）フェーズと「クリア」（論理的な偽）フェーズがあります。2つのフェーズの長さは異なる場合があります。APIは、アサートされたフェーズへの移行時に「アサートタイムスタンプ」をキャプチャし、クリアフェーズへの移行の瞬間に「クリアタイムスタンプ」をキャプチャする場合があります。
The specific assignment of the logical values "true" and "false" with specific voltages of a PPS signal, if applicable, is outside the scope of this specification. However, these assignments SHOULD be consistent with applicable standards. Implementors of PPS sources SHOULD document these assignments.
PPS信号の特定の電圧を使用した論理値「true」および「false」の特定の割り当ては、この仕様の範囲外です。ただし、これらの割り当ては、適用される標準と一致する必要があります。PPSソースの実装者は、これらの割り当てを文書化する必要があります。
Reminder to implementors of DCD-based PPS support: TTL and RS-232C (V.24/V.28) interfaces both define the "true" state as the one having the highest positive voltage. TTL defines a nominal absence of voltage as the "false" state, but RS-232C (V.24/V.28) defines the "false" state by the presence of a negative voltage.
DCDベースのPPSサポートの実装者にリマインダー：TTLおよびRS-232C（v.24/v.28）インターフェイスは、「真の」状態を最高の正電圧を持つものとして定義します。TTLは、電圧の公称存在を「偽」状態として定義しますが、RS-232C（v.24/v.28）は、負の電圧の存在によって「偽」状態を定義します。
The API supports the direct provision of PPS events (and timestamps) to an in-kernel PPS consumer. This could be the function called "hardpps()", as described in RFC 1589 [4], but the API does not require the kernel implementation to use that function name internally. The current version of the API supports at most one in-kernel PPS consumer, and does not provide a way to explicitly name it. The implementation SHOULD impose access controls on the use of this feature.
APIは、PPSイベント（およびタイムスタンプ）の直接的な提供を船内PPS消費者にサポートしています。これは、RFC 1589 [4]で説明されているように、「hardpps（）」と呼ばれる関数である可能性がありますが、APIでは、その関数名を内部的に使用するためにカーネルの実装を必要としません。APIの現在のバージョンは、最大1つの船体PPS消費者をサポートしており、明示的に名前を付ける方法を提供していません。実装は、この機能の使用に関するアクセス制御を課す必要があります。
The API optionally supports an "echo" feature, in which events on the incoming PPS signal may be reflected through software, after the capture of the corresponding timestamp, to an output signal pin. This feature may be used to discover an upper bound on the actual delay between the edges of the PPS signal and the capture of the timestamps; such information may be useful in precise calibration of the system.
APIはオプションで「エコー」機能をサポートします。この機能では、着信PPS信号のイベントは、対応するタイムスタンプのキャプチャ後、ソフトウェアを介して出力信号ピンに反映される場合があります。この機能は、PPS信号のエッジとタイムスタンプのキャプチャの間の実際の遅延に関する上限を発見するために使用できます。このような情報は、システムの正確なキャリブレーションに役立つ場合があります。
The designation of an output pin for the echo signal, and sense and shape of the output transition, is outside the scope of this specification, but SHOULD be documented for each implementation. The output pin MAY also undergo transitions at other times besides those caused by PPS input events.
エコー信号の出力ピンの指定、および出力遷移のセンスと形状は、この仕様の範囲外ですが、実装ごとに文書化する必要があります。出力ピンは、PPS入力イベントによって引き起こされるもの以外にも、他の時間で遷移を受けることもあります。
Note: this allows an implementation of the echo feature to generate an output pulse per input pulse, or an output edge per input pulse, or an output pulse per input edge. It also allows the same signal pin to be used for several purposes simultaneously.
注：これにより、ECHO機能の実装が入力パルスごとの出力パルス、入力パルスごとの出力エッジ、または入力エッジごとの出力パルスを生成できます。また、同じ信号ピンを複数の目的に同時に使用することもできます。
Also, the API optionally provides an application with the ability to specify an offset value to be applied to captured timestamps. This can be used to correct for cable and/or radio-wave propagation delays, or to compensate for systematic jitter in the external signal. The implementation SHOULD impose access controls on the use of this feature.
また、APIはオプションで、キャプチャされたタイムスタンプに適用されるオフセット値を指定する機能を備えたアプリケーションを提供します。これを使用して、ケーブルや無線波の伝播遅延を修正したり、外部信号の系統的ジッターを補正したりするために使用できます。実装は、この機能の使用に関するアクセス制御を課す必要があります。
The data structure declarations and symbol definitions for this API will appear in the header file <sys/timepps.h>. The header file MUST define all constants described in this specification, even if they are not supported by the implementation.
このAPIのデータ構造宣言と記号定義は、ヘッダーファイル<sys/timepps.h>に表示されます。ヘッダーファイルは、実装によってサポートされていなくても、この仕様で説明されているすべての定数を定義する必要があります。
The API includes several implementation-specific types:
APIには、いくつかの実装固有のタイプが含まれています。
typedef ... pps_handle_t; /* represents a PPS source */
typedef unsigned ... pps_seq_t; /* sequence number */
The "pps_handle_t" type is an opaque scalar type used to represent a PPS source within the API.
「PPS_HANDLE_T」タイプは、API内のPPSソースを表すために使用される不透明なスカラータイプです。
The "pps_seq_t" type is an unsigned integer data type of at least 32 bits.
「PPS_SEQ_T」タイプは、少なくとも32ビットの署名されていない整数データ型です。
The precise declaration of the pps_handle_t and pps_seq_t types is system-dependent.
PPS_HANDLE_TおよびPPS_SEQ_Tタイプの正確な宣言はシステム依存です。
The API imports the standard POSIX definition for this data type:
APIは、このデータ型の標準POSIX定義をインポートします。
struct timespec {
time_t tv_sec; /* seconds */
long tv_nsec; /* nanoseconds */
};
The API defines this structure as an internal (not "on the wire") representation of the NTP "64-bit unsigned fixed-point" timestamp format [3]:
APIは、この構造を、NTPの内部（「ワイヤー上」ではなく）表現として定義します。
typedef struct ntp_fp {
unsigned int integral;
unsigned int fractional;
} ntp_fp_t;
The two fields in this structure may be declared as any unsigned integral type, each of at least 32 bits.
この構造の2つのフィールドは、それぞれ少なくとも32ビットの符号なしの積分タイプとして宣言される場合があります。
The API defines this new union as an extensible type for representing times:
APIは、この新しい組合を、時間を表すための拡張可能なタイプとして定義しています。
typedef union pps_timeu {
struct timespec tspec;
ntp_fp_t ntpfp;
unsigned long longpad[3];
} pps_timeu_t;
Future revisions of this specification may add more fields to this union.
この仕様の将来の改訂は、この組合にさらにフィールドを追加する可能性があります。
Note: adding a field to this union that is larger than 3*sizeof(long) will break binary compatibility.
注：3*sizeof（long）を超えるこの組合にフィールドを追加すると、バイナリの互換性が破壊されます。
The API defines these new data structures:
APIは、これらの新しいデータ構造を定義します。
typedef struct {
pps_seq_t assert_sequence; /* assert event seq # */
pps_seq_t clear_sequence; /* clear event seq # */
pps_timeu_t assert_tu;
pps_timeu_t clear_tu;
int current_mode; /* current mode bits */
} pps_info_t;
#define assert_timestamp assert_tu.tspec #define clear_timestamp clear_tu.tspec
#define assert_timestamp assert_tu.tspec #define clear_timestamp clear_tu.tspec
#define assert_timestamp_ntpfp assert_tu.ntpfp #define clear_timestamp_ntpfp clear_tu.ntpfp
#define assert_timestamp_ntpfp assert_tu.ntpfp #define clear_timestamp_ntpfp clear_tu.ntpfp
typedef struct {
int api_version; /* API version # */
int mode; /* mode bits */
pps_timeu_t assert_off_tu;
pps_timeu_t clear_off_tu;
} pps_params_t;
#define assert_offset assert_off_tu.tspec #define clear_offset clear_off_tu.tspec
#define assert_offset assert_off_tu.tspec #define clear_offset clear_off_tu.tspec
#define assert_offset_ntpfp assert_off_tu.ntpfp #define clear_offset_ntpfp clear_off_tu.ntpfp
#define assert_offset_ntpfp assert_off_tu.ntpfp #define clear_offset_ntpfp clear_off_off_tu.ntpfp
The "pps_info_t" type is returned on an inquiry to PPS source. It contains the timestamps for the most recent assert event, and the most recent clear event. The order in which these events were actually received is defined by the timetamps, not by any other aspect of the specification. Each timestamp field represents the value of the operating system's internal timebase when the timestamped event occurred, or as close as possible to that time (with the optional addition of a specified offset). The current_mode field contains the value of the mode bits (see section 3.3) at the time of the most recent transition was captured for this PPS source. An application can use current_mode to discover the format of the timestamps returned.
「PPS_INFO_T」タイプは、PPSソースへの問い合わせで返されます。最新のアサートイベントと最新の明確なイベントのタイムスタンプが含まれています。これらのイベントが実際に受信された順序は、仕様の他の側面ではなく、タイムタンプによって定義されます。各タイムスタンプフィールドは、タイムスタンプ付きイベントが発生したときにオペレーティングシステムの内部タイムベースの値を表します。Current_Modeフィールドには、このPPSソースに対して最新の遷移時にモードビットの値（セクション3.3を参照）が含まれています。アプリケーションは、current_modeを使用して、返されたタイムスタンプの形式を検出できます。
The assert_sequence number increases once per captured assert timestamp. Its initial value is undefined. If incremented past the largest value for the type, the next value is zero. The clear_sequence number increases once per captured clear timestamp. Its initial value is undefined, and may be different from the initial value of assert_sequence. If incremented past the largest value for the type, the next value is zero. Due to possible signal loss or excessive signal noise, the assert-sequence number and the clear-sequence number might not always increase in step with each other.
ASSERT_シーケンス数は、キャプチャされたASSERTタイムスタンプごとに1回増加します。その初期値は未定義です。タイプの最大値を超えて増加した場合、次の値はゼロです。Clear_sequence番号は、Captured Clear Timestampごとに1回増加します。その初期値は未定義であり、ASSERT_シーケンスの初期値とは異なる場合があります。タイプの最大値を超えて増加した場合、次の値はゼロです。信号損失の可能性または過剰な信号ノイズにより、アサートシーケンス数とクリアシーケンス数は、互いに常にステップが増加するとは限りません。
Note that these sequence numbers are most useful in applications where events other than PPS transitions are to be captured, which might be involved in a precision stopwatch application, for example. In such cases, the sequence numbers may be used to detect overruns, where the application has missed one or more events. They may also be used to detect an excessive event rate, or to detect that an event has failed to occur between two calls to the time_pps_fetch() function (defined later).
これらのシーケンス番号は、PPS遷移以外のイベントがキャプチャされるアプリケーションで最も有用であり、たとえば精密ストップウォッチアプリケーションに関与する可能性があることに注意してください。このような場合、シーケンス番号を使用して、アプリケーションが1つ以上のイベントを逃したオーバーランを検出することができます。また、過度のイベント率を検出したり、Time_pps_fetch（）関数の2つの呼び出しの間でイベントが発生しなかったことを検出するために使用されます（後で定義）。
In order to obtain an uninterrupted series of sequence numbers (and hence of event timestamps), it may be necessary to sample the pps_info_t values at a rate somewhat faster than the underlying event rate. For example, an application interested in both assert and clear timestamps may need to sample at least twice per second. Proper use of the sequence numbers allows an application to discover if it has missed any event timestamps due to an insufficient sampling rate.
途切れない一連のシーケンス番号（したがってイベントタイムスタンプの）を取得するには、基礎となるイベント率よりもやや高速なレートでPPS_INFO_T値をサンプリングする必要がある場合があります。たとえば、アサートとクリアタイムスタンプの両方に関心のあるアプリケーションは、少なくとも1秒あたり2回サンプリングする必要がある場合があります。シーケンス番号を適切に使用すると、サンプリングレートが不十分なため、イベントタイムスタンプを見逃したかどうかをアプリケーションが発見できます。
The pps_params_t data type is used to discover and modify parameters of a PPS source. The data type includes a mode field, described in section 3.3. It also includes an api_version field, a read-only value giving the version of the API. Currently, the only defined value is:
PPS_PARAMS_Tデータ型は、PPSソースのパラメーターを発見および変更するために使用されます。データ型には、セクション3.3で説明されているモードフィールドが含まれます。また、API_versionフィールド、APIのバージョンを与える読み取り専用値も含まれます。現在、定義された唯一の値は次のとおりです。
#define PPS_API_VERS_1 1
#define pps_api_vers_1 1
This field is present to enable binary compatibility with future versions of the API.
このフィールドは、APIの将来のバージョンとのバイナリ互換性を有効にするために存在します。
Note: the term "read-only" in this specification means that an application cannot modify the relevant data item; only the implementation can modify the value. The implementation MUST ignore attempts by the application to modify a read-only field.
注：この仕様の「読み取り専用」という用語は、アプリケーションが関連するデータ項目を変更できないことを意味します。実装のみが値を変更できます。実装は、読み取り専用フィールドを変更するためのアプリケーションによる試みを無視する必要があります。
As an OPTIONAL feature of the API, the implementation MAY support adding offsets to the timestamps that are captured. (Values of type "struct timespec" can represent negative offsets.) The assert_offset field of a pps_params_t value specifies a value to be added to generate a captured assert_timestamp. The clear_offset of a pps_params_t value field specifies a value to be added to generate a captured clear_timestamp. Since the offsets, if any, apply to all users of a given PPS source, the implementation SHOULD impose access controls on the use of this feature; for example, allowing only the super-user to set the offset values. The default value for both offsets is zero.
APIのオプションの機能として、実装は、キャプチャされたタイムスタンプへのオフセットの追加をサポートする場合があります。（タイプ "struct timespec"の値は負のオフセットを表すことができます。）pps_params_t値のassert_offsetフィールドは、キャプチャされたassert_timestampを生成するために追加する値を指定します。PPS_PARAMS_T値フィールドのCLEAR_OFFSETは、キャプチャされたCLEAR_TIMESTAMPを生成するために追加する値を指定します。オフセットは、ある場合、特定のPPSソースのすべてのユーザーに適用されるため、実装はこの機能の使用に関するアクセス制御を課す必要があります。たとえば、スーパーユーザーのみがオフセット値を設定できるようにします。両方のオフセットのデフォルト値はゼロです。
A set of mode bits is associated with each PPS source.
モードビットのセットは、各PPSソースに関連付けられています。
The bits in the mode field of the pps_params_t type are:
PPS_PARAMS_Tタイプのモードフィールドのビットは次のとおりです。
/* Device/implementation parameters */
#define PPS_CAPTUREASSERT 0x01
#define PPS_CAPTURECLEAR 0x02
#define PPS_CAPTUREBOTH 0x03
#define PPS_OFFSETASSERT 0x10 #define PPS_OFFSETCLEAR 0x20
#define pps_offsetassert 0x10 #define pps_offsetclear 0x20
#define PPS_CANWAIT 0x100
#define PPS_CANPOLL 0x200
/* Kernel actions */
#define PPS_ECHOASSERT 0x40
#define PPS_ECHOCLEAR 0x80
/* Timestamp formats */
#define PPS_TSFMT_TSPEC 0x1000
#define PPS_TSFMT_NTPFP 0x2000
These mode bits are divided into three categories:
これらのモードビットは、3つのカテゴリに分割されます。
1. Device/implementation parameters: These are parameters either of the device or of the implementation. If the implementation allows these to be changed, then these bits are read/write for users with sufficient privilege (such as the super-user), and read-only for other users. If the implementation does not allow these bits to be changed, they are read-only.
1. デバイス/実装パラメーター：これらは、デバイスまたは実装のパラメーターです。実装でこれらを変更できる場合、これらのビットは、十分な特権（スーパーユーザーなど）を持つユーザー向けに読み取り/書き込み、他のユーザーには読み取り専用です。実装でこれらのビットを変更できない場合、それらは読み取り専用です。
2. Kernel actions: These bits specify certain kernel actions to be taken on arrival of a signal. If the implementation supports one of these actions, then the corresponding bit is read/write for users with sufficient privilege (such as the super-user), and read-only for other users. If the implementation does not support the action, the corresponding bit is always zero.
2. カーネルアクション：これらのビットは、信号の到着時に実行される特定のカーネルアクションを指定します。実装がこれらのアクションのいずれかをサポートしている場合、対応するビットは、十分な特権（スーパーユーザーなど）を持つユーザーの読み取り/書き込みであり、他のユーザーには読み取り専用です。実装がアクションをサポートしていない場合、対応するビットは常にゼロです。
3. Timestamp formats: These bits indicate the set of timestamp formats available for the device. They are always read-only.
3. タイムスタンプ形式：これらのビットは、デバイスで利用可能なタイムスタンプ形式のセットを示しています。彼らは常に読み取り専用です。
In more detail, the meanings of the Device/implementation parameter mode bits are:
さらに詳しくは、デバイス/実装パラメーターモードの意味は次のとおりです。
PPS_CAPTUREASSERT If this bit is set, the assert timestamp for the associated PPS source will be captured.
pps_captureassertこのビットが設定されている場合、関連するPPSソースのアサートタイムスタンプがキャプチャされます。
PPS_CAPTURECLEAR If this bit is set, the clear timestamp for the associated PPS source will be captured.
PPS_CAPTURECLEARこのビットが設定されている場合、関連するPPSソースの明確なタイムスタンプがキャプチャされます。
PPS_CAPTUREBOTH Defined as the union of PPS_CAPTUREASSERT and PPS_CAPTURECLEAR, for convenience.
PPS_CAPTUREBOTHは、便宜上、pps_captureassertとpps_captureclearの結合として定義されています。
PPS_OFFSETASSERT If set, the assert_offset value is added to the current value of the operating system's internal timebase in order to generate the captured assert_timestamp.
PPS_OFFSETASSERT SETの場合、ASSERT_OFFSET値は、キャプチャされたASSERT_TIMESTAMPを生成するために、オペレーティングシステムの内部タイムベースの現在の値に追加されます。
PPS_OFFSETCLEAR If set, the clear_offset value is added to the current value of the operating system's internal timebase in order to generate the captured clear_timestamp.
PPS_OFFSETCLEAR SETの場合、CLEAR_OFFSET値は、キャプチャされたCLEAR_TIMESTAMPを生成するために、オペレーティングシステムの内部タイムベースの現在の値に追加されます。
PPS_CANWAIT If set, the application may request that the time_pps_fetch() function (see section 3.4.3) should block until the next timestamp arrives. Note: this mode bit is read-only.
PPS_CANWAITセットの場合、アプリケーションは、次のタイムスタンプが到着するまで、time_pps_fetch（）関数（セクション3.4.3を参照）をブロックすることを要求する場合があります。注：このモードビットは読み取り専用です。
PPS_CANPOLL This bit is reserved for future use. An application SHOULD NOT depend on any functionality implied either by its presence or by its absence.
pps_canpollこのビットは、将来の使用のために予約されています。アプリケーションは、その存在や不在のいずれかによって暗示される機能に依存してはなりません。
If neither PPS_CAPTUREASSERT nor PPS_CAPTURECLEAR is set, no valid timestamp will be available via the API.
pps_captureassertもpps_captureclearも設定されていない場合、APIを介して有効なタイムスタンプは利用できません。
The meanings of the Kernel action mode bits are:
カーネルアクションモードビットの意味は次のとおりです。
PPS_ECHOASSERT If set, after the capture of an assert timestamp, the implementation generates a signal transition as rapidly as possible on an output signal pin. This MUST NOT affect the delay between the PPS source's transition to the asserted phase and the capture of the assert timestamp.
PPS_ECHOASSERTセットの場合、アサートタイムスタンプをキャプチャした後、実装は出力信号ピンでできるだけ迅速に信号遷移を生成します。これは、主張された段階へのPPSソースの移行とアサートタイムスタンプのキャプチャとの間の遅延に影響してはなりません。
PPS_ECHOCLEAR If set, after the capture of a clear timestamp, the implementation generates a signal transition as rapidly as possible on an output signal pin. This MUST NOT affect the delay between the PPS source's transition to the clear phase and the capture of the clear timestamp.
PPS_ECOCLEAR SETの場合、明確なタイムスタンプをキャプチャした後、実装により、出力信号ピンでできるだけ迅速に信号遷移が生成されます。これは、PPSソースのクリアフェーズへの移行とクリアタイムスタンプのキャプチャとの間の遅延に影響を与えてはなりません。
The timestamp formats are:
タイムスタンプ形式は次のとおりです。
PPS_TSFMT_TSPEC Timestamps and offsets are represented as values of type "struct timespec". All implementations MUST support this format, and this format is the default unless an application specifies otherwise.
PPS_TSFMT_TSPECタイムスタンプとオフセットは、タイプ「struct timespec」の値として表されます。すべての実装はこの形式をサポートする必要があります。この形式は、アプリケーションが特に指定しない限りデフォルトです。
PPS_TSFMT_NTPFP Timestamps and offsets are represented as values of type "ntp_fp_t", which corresponds to the NTP "64-bit unsigned fixed-point" timestamp format [3]. Support for this format is OPTIONAL.
PPS_TSFMT_NTPFPタイムスタンプとオフセットは、NTP "64ビットの固定点"タイムスタンプ形式[3]に対応するタイプ "ntp_fp_t"の値として表されます。この形式のサポートはオプションです。
Other timestamp format bits may be defined as fields are added to the "pps_timeu_t" union.
その他のタイムスタンプ形式のビットは、フィールドが「PPS_TIMEU_T」ユニオンに追加されるように定義できます。
The operating system may implement all of these mode bits, or just a subset of them. If an attempt is made to set an unsupported mode bit, the API will return an error. If an attempt is made to modify a read-only mode bit, the API will return an error.
オペレーティングシステムは、これらすべてのモードビット、またはそれらのサブセットのみを実装できます。サポートされていないモードビットを設定する試みが行われた場合、APIはエラーを返します。読み取り専用モードビットを変更する試みが行われた場合、APIはエラーを返します。
In the description of functions that follows, we use the following function parameters:
以下の関数の説明では、次の関数パラメーターを使用します。
filedes A file descriptor (type: int), for a serial line or other source of PPS events.
シリアルラインまたはPPSイベントのその他のソースのファイル記述子（タイプ：int）を提出します。
ppshandle A variable of type "pps_handle_t", as defined in section 3.2.
PPSHANDLEセクション3.2で定義されているように、「pps_handle_t」のタイプの変数。
ppsinfobuf A record of type "pps_info_t", as defined in section 3.2.
PPSINFOBUFセクション3.2で定義されているように、「PPS_INFO_T」というタイプのレコード。
ppsparams A record of type "pps_params_t", as defined in section 3.2.
PPSPARAMSセクション3.2で定義されているように、「PPS_PARAMS_T」というタイプのレコード。
tsformat An integer with exactly one of the timestamp format bits set.
tsformatタイムスタンプ形式のビットセットの1つを備えた整数。
The API includes functions to create and destroy PPS source "handles".
APIには、PPSソース「ハンドル」を作成および破壊する機能が含まれています。
SYNOPSIS
概要
int time_pps_create(int filedes, pps_handle_t *handle);
int time_pps_destroy(pps_handle_t handle);
DESCRIPTION
説明
All of the other functions in the PPS API operate on PPS handles (type: pps_handle_t). The time_pps_create() is used to convert an already-open UNIX file descriptor, for an appropriate special file, into a PPS handle.
PPS APIの他のすべての関数は、PPSハンドルで動作します（タイプ：PPS_HANDLE_T）。time_pps_create（）は、適切な特別なファイルに対して、すでに開いたUnixファイル記述子をPPSハンドルに変換するために使用されます。
The definition of what special files are appropriate for use with the PPS API is outside the scope of this specification, and may vary based on both operating system implementation, and local system configuration. One typical case is a serial line, whose DCD pin is connected to a source of PPS events.
PPS APIで使用するのに適している特別なファイルの定義は、この仕様の範囲外であり、オペレーティングシステムの実装とローカルシステム構成の両方によって異なる場合があります。典型的なケースの1つは、DCDピンがPPSイベントのソースに接続されているシリアルラインです。
The mode in which the UNIX file descriptor was originally opened affects what operations are allowed on the PPS handle. The time_pps_setparams() and time_pps_kcbind() functions (see sections 3.4.2 and 3.4.4) SHOULD be prohibited by the implementation if the descriptor is open only for reading (O_RDONLY).
UNIXファイル記述子が最初に開かれたモードは、PPSハンドルで許可されている操作に影響します。Time_pps_setParams（）およびtime_pps_kcbind（）関数（セクション3.4.2および3.4.4を参照）は、記述子が読み取り専用に開いている場合は、実装によって禁止される必要があります（o_rdonly）。
Note: operations on a descriptor opened with an inappropriate mode might fail with EBADF.
注：不適切なモードで開かれた記述子の操作は、EBADFで失敗する可能性があります。
The time_pps_destroy() function makes the PPS handle unusable, and frees any storage that might have been allocated for it. It does not close the associated file descriptor, nor does it change any of the parameter settings for the PPS source.
time_pps_destroy（）関数により、PPSハンドルが使用できなくなり、割り当てられた可能性のあるストレージを無料にします。関連するファイル記述子を閉じませんし、PPSソースのパラメーター設定を変更しません。
Note: If this API is adapted to an operating system that does not follow UNIX conventions for representing an accessible PPS source as an integer file descriptor, the time_pps_create() function may take different parameters from those shown here.
注：このAPIが、アクセス可能なPPSソースを整数ファイル記述子として表すためにUNIXコンベンションに従わないオペレーティングシステムに適合している場合、Time_PPS_Create（）関数は、ここに示されているものとは異なるパラメーターを取る場合があります。
RETURN VALUES
返品値
On successful completion, the time_pps_create() function returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
正常に完了すると、time_pps_create（）関数は0を返します。そうしないと、-1の値が返され、errnoがエラーを示すように設定されています。
If called with a valid handle parameter, the time_pps_destroy() function returns 0. Otherwise, it returns -1.
有効なハンドルパラメーターで呼び出された場合、time_pps_destroy（）関数は0を返します。それ以外の場合は-1を返します。
ERRORS
エラー
If the time_pps_create() function fails, errno may be set to one of the following values:
time_pps_create（）関数が失敗した場合、errnoは次の値のいずれかに設定される場合があります。
[EBADF] The filedes parameter is not a valid file descriptor.
[EBADF] FILEDESパラメーターは有効なファイル記述子ではありません。
[EOPNOTSUPP] The use of the PPS API is not supported for the file descriptor.
[eopnotsupp] PPS APIの使用は、ファイル記述子にはサポートされていません。
[EPERM] The process's effective user ID does not have the required privileges to use the PPS API.
[EPERM]プロセスの効果的なユーザーIDには、PPS APIを使用するために必要な特権がありません。
The API includes several functions use to set or obtain the parameters of a PPS source.
APIには、PPSソースのパラメーターを設定または取得するために使用されるいくつかの関数が含まれています。
SYNOPSIS
概要
int time_pps_setparams(pps_handle_t handle,
const pps_params_t *ppsparams);
int time_pps_getparams(pps_handle_t handle,
pps_params_t *ppsparams);
int time_pps_getcap(pps_handle_t handle, int *mode);
DESCRIPTION
説明
A suitably privileged application may use time_pps_setparams() to set the parameters (mode bits and timestamp offsets) for a PPS source. The pps_params_t type is defined in section 3.2; mode bits are defined in section 3.3. An application may use time_pps_getparams() to discover the current settings of the PPS parameters. An application that needs to change only a subset of the existing parameters must first call time_pps_getparams() to obtain the current parameter values, then set the new values using time_pps_setparams().
適切に特権のあるアプリケーションは、PPSソースのパラメーター（モードビットとタイムスタンプオフセット）を設定するために、time_pps_setparams（）を使用する場合があります。PPS_PARAMS_Tタイプは、セクション3.2で定義されています。モードビットは、セクション3.3で定義されています。アプリケーションは、time_pps_getParams（）を使用して、PPSパラメーターの現在の設定を検出する場合があります。既存のパラメーターのサブセットのみを変更する必要があるアプリケーションは、最初にtime_pps_getparams（）を呼び出して現在のパラメーター値を取得し、次にtime_pps_setparams（）を使用して新しい値を設定する必要があります。
Note: a call to time_pps_setparams() replaces the current values of all mode bits with those specified via the ppsparams argument, except those bits whose state cannot be changed. Bits might be read-only due to access controls, or because they are fixed by the implementation.
注：time_pps_setparams（）への呼び出しは、すべてのモードビットの現在の値を、状態を変更できないビットを除き、ppsparams引数を介して指定されたものに置き換えます。ビットは、アクセス制御のため、または実装によって修正されているため、読み取り専用です。
The timestamp format of the assert_offset and clear_offset fields is defined by the mode field. That is, on a call to time_pps_setparams(), the kernel interprets the supplied offset values using the timestamp format given in the mode field of the ppsparams argument. If the requested timestamp format is not supported, the time_pps_setparams() function has no effect and returns an error value. On a call to time_pps_getparams(), the kernel provides the timestamp format of the offsets by setting one of the timestamp format bits in the mode field.
assert_offsetおよびclear_offsetフィールドのタイムスタンプ形式は、モードフィールドによって定義されます。つまり、time_pps_setparams（）への呼び出しで、カーネルは、ppsparams引数のモードフィールドに与えられたタイムスタンプ形式を使用して、付属のオフセット値を解釈します。要求されたタイムスタンプ形式がサポートされていない場合、time_pps_setparams（）関数は効果がなく、エラー値を返します。time_pps_getParams（）への呼び出しで、カーネルは、モードフィールドにタイムスタンプ形式のビットのいずれかを設定することにより、オフセットのタイムスタンプ形式を提供します。
Note: an application that uses time_pps_getparams() to read the current offset values cannot specify which format is used. The implementation SHOULD return the offsets using the same timestamp format as was used when the offsets were set.
注：time_pps_getparams（）を使用して現在のオフセット値を読み取るアプリケーションでは、使用される形式を指定できません。実装は、オフセットが設定されたときに使用されたのと同じタイムスタンプ形式を使用してオフセットを返す必要があります。
An application wishing to discover which mode bits it may set, with its current effective user ID, may call time_pps_getcap(). This function returns the set of mode bits that may be set by the application, without generating an EINVAL or EPERM error, for the specified PPS source. It does not return the current values for the mode bits. A call to time_pps_getcap() returns the mode bits corresponding to all supported timestamp formats.
現在の効果的なユーザーIDを使用して、どのモードビットが設定されるかを発見したいアプリケーションは、time_pps_getcap（）を呼び出すことができます。この関数は、指定されたPPSソースに対して、EINVALまたはEPERMエラーを生成することなく、アプリケーションによって設定される可能性のあるモードビットのセットを返します。モードビットの現在の値は返されません。time_pps_getCap（）への呼び出しは、サポートされているすべてのタイムスタンプ形式に対応するモードビットを返します。
The time_pps_getcap() function MAY ignore the mode in which the associated UNIX file descriptor was opened, so the application might still receive an EBADF error on a call to time_pps_setparams(), even if time_pps_getcap() says that the chosen mode bits are allowed.
time_pps_getCap（）関数は、関連するUNIXファイル記述子が開かれたモードを無視する可能性があるため、Time_pps_getCap（）が選択した場合でも、アプリケーションはまだtime_pps_setparams（）への呼び出しでEBADFエラーを受信する可能性があります。
The mode bits returned by time_pps_getcap() for distinct PPS handles may differ, reflecting the specific capabilities of the underlying hardware connection to the PPS source, or of the source itself.
個別のPPSハンドルに対してtime_pps_getCap（）によって返されるモードビットは、PPSソースまたはソース自体の基礎となるハードウェア接続の特定の機能を反映して異なる場合があります。
RETURN VALUES
返品値
On successful completion, the time_pps_setparams(), time_pps_getparams(), and time_pps_getcap() functions return 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
正常に完了すると、time_pps_setparams（）、time_pps_getparams（）、およびtime_pps_getcap（）関数が0を返します。そうしないと、-1の値が返され、errnoがエラーを示すように設定されます。
ERRORS
エラー
If the time_pps_setparams(), time_pps_getparams(), or time_pps_getcap() function fails, errno may be set to one of the following values:
time_pps_setparams（）、time_pps_getparams（）、またはtime_pps_getcap（）関数が失敗した場合、errnoは次の値のいずれかに設定できます。
[EBADF] The handle parameter is not associated with a valid file descriptor, or the descriptor is not open for writing.
[EBADF]ハンドルパラメーターは有効なファイル記述子に関連付けられていないか、記述子が書き込むために開いていません。
[EFAULT] A parameter points to an invalid address.
[efault]パラメーターは無効なアドレスを指します。
[EOPNOTSUPP] The use of the PPS API is not supported for the associated file descriptor.
[eopnotsupp] PPS APIの使用は、関連するファイル記述子に対してサポートされていません。
[EINVAL] The operating system does not support all of the requested mode bits.
[Einval]オペレーティングシステムは、要求されたすべてのモードビットをサポートするわけではありません。
[EPERM] The process's effective user ID does not have the required privileges to use the PPS API, or to set the given mode bits.
[EPERM]プロセスの効果的なユーザーIDには、PPS APIを使用したり、指定されたモードビットを設定するために必要な特権がありません。
The API includes one function that gives applications access to PPS timestamps. As an implementation option, the application may request the API to block until the next timestamp is captured. (The API does not directly support the use of the select() or poll() system calls to wait for PPS events.)
APIには、PPSタイムスタンプへのアプリケーションアクセスを提供する1つの関数が含まれています。実装オプションとして、アプリケーションは、次のタイムスタンプがキャプチャされるまでAPIをブロックするように要求する場合があります。（APIは、PPSイベントを待つためにSelect（）またはPoll（）システムの呼び出しの使用を直接サポートしていません。）
SYNOPSIS
概要
int time_pps_fetch(pps_handle_t handle, const int tsformat, pps_info_t *ppsinfobuf, const struct timespec *timeout);
int time_pps_fetch（pps_handle_tハンドル、const int tsformat、pps_info_t *ppsinfobuf、const struct timespec *timeout）;
DESCRIPTION
説明
An application may use time_pps_fetch() to obtain the most recent timestamps captured for the PPS source specified by the handle parameter. The tsformat parameter specifies the desired timestamp format; if the requested timestamp format is not supported, the call fails and returns an error value. The application MUST specify exactly one timestamp format.
アプリケーションは、time_pps_fetch（）を使用して、ハンドルパラメーターで指定されたPPSソース用にキャプチャされた最新のタイムスタンプを取得する場合があります。TSFORMATパラメーターは、目的のタイムスタンプ形式を指定します。要求されたタイムスタンプ形式がサポートされていない場合、コールは失敗し、エラー値を返します。アプリケーションは、1つのタイムスタンプ形式を正確に指定する必要があります。
This function blocks until either a timestamp is captured from the PPS source, or until the specified timeout duration has expired. If the timeout parameter is a NULL pointer, the function simply blocks until a timestamp is captured. If the timeout parameter specifies a delay of zero, the function returns immediately.
この関数は、タイムスタンプがPPSソースからキャプチャされるか、指定されたタイムアウト期間が失効するまでブロックします。タイムアウトパラメーターがnullポインターの場合、機能はタイムスタンプがキャプチャされるまで単純にブロックします。タイムアウトパラメーターがゼロの遅延を指定した場合、関数はすぐに戻ります。
Support for blocking behavior is an implementation option. If the PPS_CANWAIT mode bit is clear, and the timeout parameter is either NULL or points to a non-zero value, the function returns an EOPNOTSUPP error. An application can discover whether the feature is implemented by using time_pps_getcap() to see if the PPS_CANWAIT mode bit is set.
ブロッキング動作のサポートは実装オプションです。pps_canwaitモードビットが明確で、タイムアウトパラメーターがnullまたは非ゼロ値を指す場合、関数はeopnotsuppエラーを返します。アプリケーションは、time_pps_getcap（）を使用して機能が実装されているかどうかを発見して、pps_canwaitモードビットが設定されているかどうかを確認できます。
The result is stored in the ppsinfobuf parameter, whose fields are defined in section 3.2. If the function returns as the result of a timeout or error, the contents of the ppsinfobuf are undefined.
結果は、PPSINFOBUFパラメーターに保存され、そのフィールドはセクション3.2で定義されています。タイムアウトまたはエラーの結果として関数が戻ってきた場合、PPSINFOBUFの内容は未定義です。
If this function is invoked before the system has captured a timestamp for the signal source, the ppsinfobuf returned will have its timestamp fields set to the time format's base date (e.g., for PPS_TSFMT_TSPEC, both the tv_sec and tv_nsec fields will be zero).
システムが信号ソースのタイムスタンプをキャプチャする前にこの関数が呼び出された場合、PPSINFOBUFが返された場合、TV_SECとTV_NSECフィールドの両方がPPS_TSFMT_TSPECの場合、タイムスタンプフィールドがTIME形式のベース日付に設定されます。
RETURN VALUES
返品値
On successful completion, the time_pps_fetch() function returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
正常に完了すると、time_pps_fetch（）関数は0を返します。そうしないと、-1の値が返され、errnoがエラーを示すように設定されています。
ERRORS
エラー
If the time_pps_fetch() function fails, errno may be set to one of the following values:
time_pps_fetch（）関数が失敗した場合、errnoは次の値のいずれかに設定される場合があります。
[EBADF] The handle parameter is not associated with a valid file descriptor.
[EBADF]ハンドルパラメーターは、有効なファイル記述子に関連付けられていません。
[EFAULT] A parameter points to an invalid address.
[efault]パラメーターは無効なアドレスを指します。
[EINTR] A signal was delivered before the time limit specified by the timeout parameter expired and before a timestamp has been captured.
[EINTR]タイムアウトパラメーターによって指定された時間制限が期限切れになる前およびタイムスタンプがキャプチャされる前に、信号が配信されました。
[EINVAL] The requested timestamp format is not supported.
[einval]要求されたタイムスタンプ形式はサポートされていません。
[EOPNOTSUPP] The use of the PPS API is not supported for the associated file descriptor.
[eopnotsupp] PPS APIの使用は、関連するファイル記述子に対してサポートされていません。
[ETIMEDOUT] The timeout duration has expired.
[etimedout]タイムアウト期間の有効期限が切れています。
The API includes one OPTIONAL function to specify if and how a PPS source is provided to a kernel consumer of PPS events, such as the code used to discipline the operating system's internal timebase.
APIには、オペレーティングシステムの内部タイムベースを懲戒するために使用されるコードなど、PPSイベントのカーネル消費者にPPSソースが提供されるかどうか、どのように提供されるかを指定する1つのオプション関数が含まれています。
SYNOPSIS
概要
int time_pps_kcbind(pps_handle_t handle, const int kernel_consumer, const int edge, const int tsformat); DESCRIPTION
int time_pps_kcbind（pps_handle_tハンドル、const int kernel_consumer、const int edge、const int tsformat）;説明
An application with appropriate privileges may use time_pps_kcbind() to bind a kernel consumer to the PPS source specified by the handle.
適切な特権を持つアプリケーションは、time_pps_kcbind（）を使用して、カーネル消費者をハンドルで指定したPPSソースにバインドする場合があります。
The kernel consumer is identified by the kernel_consumer parameter. In the current version of the API, the possible values for this parameter are:
カーネル消費者は、kernel_consumerパラメーターによって識別されます。APIの現在のバージョンでは、このパラメーターの可能な値は次のとおりです。
#define PPS_KC_HARDPPS 0 #define PPS_KC_HARDPPS_PLL 1 #define PPS_KC_HARDPPS_FLL 2
#define pps_kc_hardpps 0 #define pps_kc_hardpps_pll 1 #define pps_kc_hardpps_fll 2
with these meanings:
これらの意味で：
PPS_KC_HARDPPS The kernel's hardpps() function (or equivalent).
pps_kc_hardppsカーネルのhardpps（）関数（または同等）。
PPS_KC_HARDPPS_PLL A variant of hardpps() constrained to use a phase-locked loop.
pps_kc_hardpps_pll位相ロックループを使用するように制約されているhardpps（）のバリアント。
PPS_KC_HARDPPS_FLL A variant of hardpps() constrained to use a frequency-locked loop.
PPS_KC_HARDPPS_FLL周波数ロックループを使用するように制約されているhardpps（）のバリアント。
Implementation of any or all of these values is OPTIONAL.
これらの値のいずれかまたはすべての実装はオプションです。
The edge parameter indicates which edge of the PPS signal causes a timestamp to be delivered to the kernel consumer. It may have the value PPS_CAPTUREASSERT, PPS_CAPTURECLEAR, or PPS_CAPTUREBOTH, depending on particular characteristics of the PPS source. It may also be zero, which removes any binding between the PPS source and the kernel consumer.
エッジパラメーターは、PPS信号のどのエッジがタイムスタンプをカーネル消費者に配信するかを示します。PPSソースの特定の特性に応じて、値pps_captureassert、pps_captureclear、またはpps_capturebothがある場合があります。また、ゼロである可能性があり、PPSソースとカーネル消費者の間のバインディングが削除されます。
The tsformat parameter specifies the format for the timestamps delivered to the kernel consumer. If this value is zero, the implementation MAY choose the appropriate format, or return EINVAL. The implementation MAY ignore a non-zero value for this parameter.
TSFORMATパラメーターは、カーネル消費者に配信されるタイムスタンプの形式を指定します。この値がゼロの場合、実装は適切な形式を選択するか、einvalを返す場合があります。実装は、このパラメーターのゼロ以外の値を無視する場合があります。
The binding created by this call persists until it is changed by a subsequent call specifying the same kernel_consumer. In particular, a subsequent call to time_pps_destroy() for the specified handle does not affect the binding.
この呼び出しによって作成されたバインディングは、同じkernel_consumerを指定する後続の呼び出しによって変更されるまで持続します。特に、指定されたハンドルのtime_pps_destroy（）への後続の呼び出しは、バインディングに影響しません。
The binding is independent of any prior or subsequent changes to the PPS_CAPTUREASSERT and PPS_CAPTURECLEAR mode bits for the device. However, if either the edge or the tsformat parameter values are inconsistent with the capabilities of the PPS source, an error is returned. The implementation MAY also return an error if the tsformat value is unsupported for time_pps_kcbind(), even if it is supported for other uses of the API.
このバインディングは、デバイスのPPS_CaptureAsSertおよびPPS_CaptureClearモードビットの以前またはその後の変更に依存しません。ただし、EDGEまたはTSFORMATパラメーター値のいずれかがPPSソースの機能と矛盾している場合、エラーが返されます。また、APIの他の使用でサポートされていても、tsformat値がtime_pps_kcbind（）に対してサポートされていない場合、実装はエラーを返す場合があります。
The operating system may enforce two restrictions on the bindings created by time_pps_kcbind():
オペレーティングシステムは、time_pps_kcbind（）によって作成されたバインディングに2つの制限を実施する場合があります。
1. the kernel MAY return an error if an attempt is made to bind a kernel consumer to more than one PPS source a time.
1. カーネル消費者を時間に複数のPPSソースにバインドしようとする試みが行われた場合、カーネルはエラーを返すことができます。
2. the kernel MAY restrict the ability to set bindings to processes with sufficient privileges to modify the system's internal timebase. (On UNIX systems, such modification is normally done using settimeofday() and/or adjtime(), and is restricted to users with superuser privilege.)
2. カーネルは、システムの内部タイムベースを変更するのに十分な特権を持つプロセスにバインディングを設定する機能を制限する場合があります。（UNIXシステムでは、そのような変更は通常、settimeofday（）および/またはadjtime（）を使用して行われ、スーパーユーザーの特権を持つユーザーに制限されています。）
Warning: If this feature is configured for a PPS source that does not have an accurate 1-pulse-per-second signal, or is otherwise inappropriately configured, use of this feature may result in seriously incorrect timekeeping for the entire system. For best results, the 1-PPS signal should have much better frequency stability than the system's internal clock source (usually a crystal-controlled oscillator), and should have jitter (variation in interarrival time) much less than the system's clock-tick interval.
警告：この機能が、正確な1パルスあたりの信号を持たないPPSソースに対して構成されている場合、または不適切に構成されている場合、この機能を使用すると、システム全体のタイムキーピングが大幅に不正確になる可能性があります。最良の結果を得るために、1-PPS信号は、システムの内部クロックソース（通常はクリスタル制御オシレーター）よりもはるかに優れた周波数安定性を持つ必要があり、システムのクロックチックインターバルよりもはるかに少ないジッター（到着時間の変動）が必要です。
See RFC 1589 [4] for more information about how the system's timebase may be disciplined using a PPS signal.
PPS信号を使用してシステムのタイムベースがどのように懲戒処分されるかの詳細については、RFC 1589 [4]を参照してください。
RETURN VALUES
返品値
On successful completion, the time_pps_kcbind() function returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
正常に完了すると、time_pps_kcbind（）関数が0を返します。そうでない場合、-1の値が返され、errnoがエラーを示すように設定されています。
ERRORS
エラー
If the time_pps_kcbind() function fails, errno may be set to one of the following values:
time_pps_kcbind（）関数が失敗した場合、errnoは次の値のいずれかに設定される場合があります。
[EBADF] The handle parameter is not associated with a valid file descriptor, or the descriptor is not open for writing.
[EBADF]ハンドルパラメーターは有効なファイル記述子に関連付けられていないか、記述子が書き込むために開いていません。
[EFAULT] A parameter points to an invalid address.
[efault]パラメーターは無効なアドレスを指します。
[EINVAL] The requested timestamp format is not supported.
[einval]要求されたタイムスタンプ形式はサポートされていません。
[EOPNOTSUPP] The use of the PPS API is not supported for the associated file descriptor, or this OPTIONAL function is not supported.
[eopnotsupp] PPS APIの使用は、関連するファイル記述子に対してサポートされていません。または、このオプションの関数はサポートされていません。
[EPERM] The process's effective user ID does not have the required privileges to set the binding.
[EPERM]プロセスの効果的なユーザーIDには、バインディングを設定するために必要な特権がありません。
The key words "MUST", "MUST NOT", "REQUIRED","SHOULD", SHOULD NOT", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [1].
このドキュメントの「必須」、「必須」、「必須」、「必須」、「必要」、「5月」、「5月」、「可能な」、「必要はない」は、RFC 2119 [1]に記載されているように解釈されます。
Some features of this specification are OPTIONAL, but others are REQUIRED.
この仕様のいくつかの機能はオプションですが、他の機能が必要です。
An implementation MUST provide these functions:
実装はこれらの機能を提供する必要があります。
- time_pps_create() - time_pps_destroy() - time_pps_setparams() - time_pps_getparams() - time_pps_getcap() - time_pps_fetch()
- time_pps_create（） - time_pps_destroy（） - time_pps_setparams（） - time_pps_getparams（） - time_pps_getcap（） - time_pps_fetch（）
An implementation MUST provide this function, but it may be implemented as a function that always return an EOPNOTSUPP error, possibly on a per-source basis:
実装はこの関数を提供する必要がありますが、おそらくソースごとにeopnotsuppエラーを常に返す関数として実装される場合があります。
- time_pps_kcbind()
- time_pps_kcbind（）
An implementation MUST support at least one of these mode bits for each PPS source:
実装は、各PPSのこれらのモードビットの少なくとも1つをサポートする必要があります。ソース：
- PPS_CAPTUREASSERT - PPS_CAPTURECLEAR
- PPS_CAPTUREASSERT -PPS_CAPTURECLEAR
and MAY support both of them. If an implementation supports both of these bits for a PPS source, it SHOULD allow them to be set simultaneously.
両方をサポートする場合があります。実装がPPSソースのこれらのビットの両方をサポートする場合、それらを同時に設定できるようにする必要があります。
An implementation MUST support this timestamp format:
実装は、このタイムスタンプ形式をサポートする必要があります。
- PPS_TSFMT_TSPEC
- pps_tsfmt_tspec
An implementation MAY support these mode bits:
実装は、これらのモードビットをサポートする場合があります。
- PPS_ECHOASSERT - PPS_ECHOCLEAR - PPS_OFFSETASSERT - PPS_OFFSETCLEAR
- PPS_ECHOASSERT -PPS_ECOCLEAR -PPS_OFFSETASSERT -PPS_OFFSETCLEAR
An implementation MAY support this timestamp format:
実装は、このタイムスタンプ形式をサポートする場合があります。
- PPS_TSFMT_NTPFP
- pps_tsfmt_ntpfp
A very simple use of this API might be:
このAPIの非常に簡単な使用は、次のとおりです。
int fd;
pps_handle_t handle;
pps_params_t params;
pps_info_t infobuf;
struct timespec timeout;
/* Open a file descriptor and enable PPS on rising edges */
fd = open(PPSfilename, O_RDWR, 0);
time_pps_create(fd, &handle);
time_pps_getparams(handle, ¶ms);
if ((params.mode & PPS_CAPTUREASSERT) == 0) {
fprintf(stderr, "%s cannot currently CAPTUREASSERT\n",
PPSfilename);
exit(1);
}
/* create a zero-valued timeout */
timeout.tv_sec = 0;
timeout.tv_nsec = 0;
/* loop, printing the most recent timestamp every second or so */
while (1) {
sleep(1);
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);
printf("Assert timestamp: %d.%09d, sequence: %ld\n",
infobuf.assert_timestamp.tv_sec,
infobuf.assert_timestamp.tv_nsec,
infobuf.assert_sequence);
}
Note that this example omits most of the error-checking that would be expected in a reliable program.
この例は、信頼できるプログラムで予想されるエラーチェックのほとんどを省略していることに注意してください。
Also note that, on a system that supports PPS_CANWAIT, the function of these lines:
また、pps_canwaitをサポートするシステムでは、これらの行の機能が次のことに注意してください。
sleep(1);
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);
might be more reliably accomplished using:
以下を使用して、より確実に達成される可能性があります。
timeout.tv_sec = 100;
timeout.tv_nsec = 0;
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);
The (arbitrary) timeout value is used to protect against the possibility that another application might disable PPS timestamps, or that the hardware generating the timestamps might fail.
（任意の）タイムアウト値は、別のアプリケーションがPPSタイムスタンプを無効にする可能性から保護するために、またはタイムスタンプを生成するハードウェアが失敗する可能性から保護するために使用されます。
A slightly more elaborate use of this API might be:
このAPIの少し精巧な使用は、次のとおりです。
int fd;
pps_handle_t handle;
pps_params_t params;
pps_info_t infobuf;
int avail_mode;
struct timespec timeout;
/* Open a file descriptor */
fd = open(PPSfilename, O_RDWR, 0);
time_pps_create(fd, &handle);
/*
* Find out what features are supported
*/
time_pps_getcap(handle, &avail_mode);
if ((avail_mode & PPS_CAPTUREASSERT) == 0) {
fprintf(stderr, "%s cannot CAPTUREASSERT\n", PPSfilename);
exit(1);
}
if ((avail_mode & PPS_OFFSETASSERT) == 0) {
fprintf(stderr, "%s cannot OFFSETASSERT\n", PPSfilename);
exit(1);
}
/*
* Capture assert timestamps, and
* compensate for a 675 nsec propagation delay
*/
time_pps_getparams(handle, ¶ms);
params.assert_offset.tv_sec = 0;
params.assert_offset.tv_nsec = 675;
params.mode |= PPS_CAPTUREASSERT | PPS_OFFSETASSERT;
time_pps_setparams(handle, ¶ms);
/* create a zero-valued timeout */
timeout.tv_sec = 0;
timeout.tv_nsec = 0;
/* loop, printing the most recent timestamp every second or so */
while (1) {
if (avail_mode & PPS_CANWAIT) {
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, NULL);
/* waits for the next event */
} else {
sleep(1);
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf,
timeout);
}
printf("Assert timestamp: %d.%09d, sequence: %ld\n",
infobuf.assert_timestamp.tv_sec,
infobuf.assert_timestamp.tv_nsec,
infobuf.assert_sequence);
}
Again, most of the necessary error-checking has been omitted from this example.
繰り返しますが、必要なエラーチェックのほとんどは、この例から省略されています。
4 Security Considerations
4つのセキュリティ上の考慮事項
This API gives applications three capabilities:
このAPIは、アプリケーションに3つの機能を提供します。
- Causing the system to capture timestamps on certain events.
- 特定のイベントでシステムがタイムスタンプをキャプチャします。
- Obtaining timestamps for certain events.
- 特定のイベントのタイムスタンプを取得します。
- Affecting the system's internal timebase.
- システムの内部タイムベースに影響します。
The first capability should not affect security directly, but might cause a slight increase in interrupt latency and interrupt-handling overhead.
最初の機能は、セキュリティに直接影響を与えるべきではありませんが、割り込み遅延と割り込み処理のオーバーヘッドがわずかに増加する可能性があります。
The second capability might be useful in implementing certain kinds of covert communication channels.
2番目の機能は、特定の種類の秘密のコミュニケーションチャネルを実装するのに役立つ場合があります。
In most cases, neither of these first two issues is a significant security threat, because the traditional UNIX file protection facility may be used to to limit access to the relevant special files. Provision of the PPS API adds minimal additional risk.
ほとんどの場合、これらの最初の2つの問題はどちらも重要なセキュリティの脅威ではありません。これは、従来のUNIXファイル保護機能を使用して、関連する特別なファイルへのアクセスを制限するために使用される可能性があるためです。PPS APIの提供は、最小限の追加リスクを追加します。
The final capability is reserved to highly privileged users. In UNIX systems, this means those with superuser privilege. Such users can evade protections based on file permissions; however, such users can in general cause unbounded havoc, and can set the internal timebase (and its rate of change), so this API creates no new vulnerabilities.
最終的な機能は、非常に特権のあるユーザーに予約されています。UNIXシステムでは、これはスーパーユーザーの特権を持つ人々を意味します。このようなユーザーは、ファイル許可に基づいて保護を回避できます。ただし、そのようなユーザーは一般に、組み込みのない大混乱を引き起こす可能性があり、内部タイムベース（およびその変更率）を設定することができるため、このAPIは新しい脆弱性を作成しません。
5 Acknowledgements
5謝辞
The API in this document draws some of its inspiration from the LBL "ppsclock" distribution [2], originally implemented in 1993 by Steve McCanne, Craig Leres, and Van Jacobson. We also thank Poul-Henning Kamp, Craig Leres, Judah Levine, and Harlan Stenn for helpful comments they contributed during the drafting of this document.
このドキュメントのAPIは、1993年にSteve McCanne、Craig Leres、およびVan Jacobsonによって1993年に実装されたLBL「PPSCrock」分布[2]からインスピレーションの一部を導入しています。また、Poul-Henning Kamp、Craig Leres、Judah Levine、およびHarlan Stennに感謝します。
6 References
6リファレンス
1. Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
1. Bradner、S。、「要件レベルを示すためにRFCで使用するためのキーワード」、BCP 14、RFC 2119、1997年3月。
2. Steve McCanne, Craig Leres, and Van Jacobson. PPSCLOCK. ftp://ftp.ee.lbl.gov/ppsclock.tar.Z.
2. スティーブ・マッキャンヌ、クレイグ・レレス、ヴァン・ジェイコブソン。ppscrock。ftp://ftp.ee.lbl.gov/ppsclock.tar.z。
3. Mills, D., "Network Time Protocol (Version 3): Specification, Implementation and Analysis", RFC 1305, March 1992.
3. Mills、D。、「ネットワークタイムプロトコル（バージョン3）：仕様、実装、分析」、RFC 1305、1992年3月。
4. Mills, D., "A Kernel Model for Precision Timekeeping", RFC 1589, March, 1994.
4. Mills、D。、「精密タイムキーピングのためのカーネルモデル」、RFC 1589、1994年3月。
5. The Open Group. The Single UNIX Specification, Version 2 - 6 Vol Set for UNIX 98. Document number T912, The Open Group, February, 1997.
5. オープングループ。単一のUnix仕様、バージョン2-6 Vol unix 98用のVolセット。ドキュメント番号T912、Open Group、1997年2月。
7 Authors' Addresses
7著者の住所
Jeffrey C. Mogul Western Research Laboratory Compaq Computer Corporation 250 University Avenue Palo Alto, California, 94305, U.S.A.
ジェフリーC.モーグルウエスタンリサーチラボラトリーコンパックコンピューターコーポレーション250ユニバーシティアベニューパロアルト、カリフォルニア、94305、米国
Phone: 1 650 617 3304 (email preferred) EMail: mogul@wrl.dec.com
電話：1 650 617 3304（電子メール優先）メール：mogul@wrl.dec.com
David L. Mills Electrical and Computer Engineering Department University of Delaware Newark, DE 19716
David L. Mills Electrical and Computer Engineering Department of Delaware Newark、de 19716
Phone: (302) 831-8247 EMail: mills@udel.edu
電話：（302）831-8247メール：mills@udel.edu
Jan Brittenson Sun Microsystems, Inc. 901 San Antonio Rd M/S MPK17-202 Palo Alto, CA 94303 Email: Jan.Brittenson@Eng.Sun.COM
Jan Brittenson Sun Systems、Inc。901 San Antonio RD M/S MPK17-202 Palo Alto、CA 94303 Email：jan.brittenson@eng.sun.com
Jonathan Stone Stanford Distributed Systems Group Stanford, CA 94305
ジョナサンストーンスタンフォード分散システムグループスタンフォード、カリフォルニア94305
Phone: (650) 723-2513 EMail: jonathan@dsg.stanford.edu
電話：（650）723-2513メール：jonathan@dsg.stanford.edu
Ulrich Windl Universitaet Regensburg, Klinikum
ウルリッヒ・ウィンドル大学レーゲンスバーグ、クリニカム
EMail: ulrich.windl@rz.uni-regensburg.de
A. Extensions and related APIs
A.拡張および関連API
The API specified in the main body of this document could be more useful with the provision of several extensions or companion APIs.
このドキュメントの本体で指定されたAPIは、いくつかの拡張機能またはコンパニオンAPIの提供により、より有用になる可能性があります。
At present, the interfaces listed in this appendix are not part of the formal specification in this document.
現在、この付録にリストされているインターフェイスは、このドキュメントの正式な仕様の一部ではありません。
The "echo" mechanism described in the body of this specification leaves most of the details to the implementor, especially the designation of one or more output pins.
この仕様の本体に記載されている「エコー」メカニズムは、ほとんどの詳細を実装者、特に1つ以上の出力ピンの指定に残します。
It might be useful to extend this API to provide either or both of these features:
これらの機能のいずれかまたは両方を提供するために、このAPIを拡張することは有用かもしれません。
- A means by which the application can discover which output pin is echoing the input pin.
- アプリケーションが入力ピンをエコーしている出力ピンを発見できる手段。
- A means by which the application can select which output pin is echoing the input pin.
- アプリケーションが入力ピンをエコーしている出力ピンを選択できる手段。
The PPS API may be useful with a wide variety of reference clocks, connected via several different interface technologies (including serial lines, parallel interfaces, and bus-level interfaces). These reference clocks can have many features and parameters, some of which might not even have been invented yet.
PPS APIは、いくつかの異なるインターフェイステクノロジー（シリアルライン、平行インターフェイス、バスレベルインターフェイスを含む）で接続された、さまざまな参照クロックで役立つ場合があります。これらの参照クロックには、多くの機能とパラメーターがありますが、その一部はまだ発明されていない可能性があります。
We believe that it would be useful to have a mechanism by which an application can discover arbitrary features and parameters of a reference clock. These might include:
私たちは、アプリケーションが参照クロックの任意の特徴とパラメーターを発見できるメカニズムを持つことが有用であると考えています。これらには以下が含まれます。
- Clock manufacturer, model number, and revision level - Whether the clock is synchronized to an absolute standard - For synchronized clocks, * The specific standard * The accuracy of the standard * The path used (direct connection, shortwave, longwave, satellite, etc.) * The distance (offset) and variability of this path
- クロックメーカー、モデル番号、および改訂レベル - クロックが絶対標準に同期されるかどうか - 同期クロックの場合、 *特定の標準 *標準の精度 *使用されたパス（直接接続、短波、長波、衛星など。） *このパスの距離（オフセット）と変動性
- For PPS sources, * The pulse rate * The pulse shape * Which edge of the pulse corresponds to the epoch
- PPSソースの場合、 *パルス速度 *パルス形状 *パルスのエッジはエポックに対応しています
- The time representation format
- 時間表現形式
This information might best be provided by an API analogous to the standard "curses" API, with a database analogous to the standard "terminfo" database. That is, a "clockinfo" database would contain a set of (attribute, value) pairs for each type of clock, and the API would provide a means to query this database.
この情報は、標準の「Terminfo」データベースに類似したデータベースを使用して、標準の「Curses」APIに類似したAPIによって最もよく提供される場合があります。つまり、「clockinfo」データベースには、各タイプのクロックの（属性、値）ペアのセットが含まれ、APIはこのデータベースを照会する手段を提供します。
Additional mechanisms would allow an application to discover the clock or clocks connected to the local system, and to discover the clockinfo type of a specific clock device.
追加のメカニズムにより、アプリケーションはローカルシステムに接続されているクロックまたはクロックを発見し、特定のクロックデバイスのclockinfoタイプを発見できます。
Although the clockinfo database described in section A.2, together with the discover mechanisms described there, would allow an application to discover the PPS source (or sources) connected to a system, it might be more complex than necessary.
セクションA.2で説明したClockINFOデータベースは、そこに記載されている発見メカニズムとともに、アプリケーションがシステムに接続されたPPSソース（またはソース）を発見できるようになりますが、必要以上に複雑になる可能性があります。
A simpler approach would be to support a single function that provides the identity of one or more PPS sources.
より簡単なアプローチは、1つ以上のPPSソースのアイデンティティを提供する単一の関数をサポートすることです。
For example, the function might be declared as
たとえば、関数はとして宣言される場合があります
int time_pps_findsource(int index, char *path, int pathlen, char *idstring, int idlen);
int time_pps_findsource（int index、char *path、int pathlen、char *idstring、int idlen）;
The index argument implicitly sets up an ordering on the PPS sources attached to the system. An application would use this function to inquire about the Nth source. The function would return -1 if no such source exists; otherwise, it would return 0, and would place the pathname of the associated special file in the path argument. It would also place an identification string in the idstring argument. The identification string could include the clock make, model, version, etc., which could then be used by the application to control its behavior.
インデックス引数は、システムに接続されたPPSソースの順序を暗黙的に設定します。アプリケーションは、この関数を使用して、n番目のソースについて問い合わせます。そのようなソースが存在しない場合、関数は-1を返します。それ以外の場合は、0を返し、関連する特別ファイルのパス名をパス引数に配置します。また、IDString引数に識別文字列を配置します。識別文字列には、クロックメイク、モデル、バージョンなどを含めることができ、その後、アプリケーションが動作を制御するために使用できます。
This function might simply read the Nth line from a simple database, containing lines such as:
この関数は、次のような線を含む単純なデータベースからnth Lineを単に読み取る場合があります。
/dev/tty00 "TrueTime 468-DC" /dev/pps1 "Homebrew rubidium frequency standard"
/dev/tty00 "Truetime 468-dc"/dev/pps1 "Homebrew Rubidium頻度標準"
allowing the system administrator to describe the configuration of PPS sources.
システム管理者がPPSソースの構成を説明できるようにします。
B. Example implementation: PPSDISC Line discipline
B.実装の例：PPSDISC Line Discipline
One possible implementation of the PPS API might be to define a new "line discipline" and then map the API onto a set of ioctl() commands. Here we sketch such an implementation; note that this is not part of the specification of the API, and applications should not expect this low-level interface to be available.
PPS APIの可能な実装の1つは、新しい「ラインの規律」を定義し、APIをIOCTL（）コマンドのセットにマッピングすることです。ここでは、そのような実装をスケッチします。これはAPIの仕様の一部ではなく、アプリケーションがこの低レベルのインターフェイスが利用可能になるとは期待してはならないことに注意してください。
In this approach, the set of line disciplines is augmented with one new line discipline, PPSDISC. This discipline will act exactly the same as the TTYDISC discipline, except for its handling of modem DCD interrupts.
このアプローチでは、ラインの分野のセットは、1つの新しいライン分野であるPPSDISCで補強されています。この規律は、モデムDCD割り込みの処理を除き、TTYDISCの規律とまったく同じように機能します。
Once the TIOCSETD ioctl() has been used to select this line discipline, PPS-related operations on the serial line may be invoked using new ioctl() commands. For example (values used only for illustration):
TIOCSETD IOCTL（）を使用してこのラインの規律を選択すると、シリアルラインのPPS関連操作がnew IoCTL（）コマンドを使用して呼び出される場合があります。たとえば（図のみに使用される値）：
#define PPSFETCH _IOR('t', 75, pps_info_t)
#define PPSSETPARAM _IOW('t', 76, pps_params_t)
#define PPSGETPARAM _IOR('t', 77, pps_params_t)
#define PPSGETCAP _IOR('t', 78, int)
A typical use might be:
典型的な使用は次のとおりです。
int ldisc = PPSDISC;
pps_params_t params;
pps_info_t infobuf;
ioctl(fd, TIOCSETD, &ldisc); /* set discipline */
/*
* Check the capabilities of this PPS source to see
* if it supports what we need.
*/
ioctl(fd, PPSGETCAP, ¶ms);
if ((params.mode & PPS_CAPTUREASSERT) == 0) {
fprintf(stderr, "PPS source is not suitable\n");
exit(1);
}
/*
* Set this line to timestamp on a rising-edge interrupt
*/
ioctl(fd, PPSGETPARAMS, ¶ms);
params.mode |= PPS_CAPTUREASSERT;
ioctl(fd, PPSSETPARAMS, ¶ms);
sleep(2); /* allow time for the PPS pulse to happen */
/* obtain most recent timestamp and sequence # for this line */
ioctl(fd, PPSFETCH, &infobuf);
Again, this example imprudently omits any error-checking.
繰り返しますが、この例では、エラーチェックが途方もなく省略されています。
C. Available implementations
C.利用可能な実装
Several available implementations of this API are listed at <http://www.ntp.org/ppsapi/PPSImpList.html>. Note that not all of these implementations correspond to the current version of the specification.
このAPIのいくつかの利用可能な実装は、<http://www.ntp.org/ppsapi/ppsimplist.html>にリストされています。これらの実装のすべてが、仕様の現在のバージョンに対応しているわけではないことに注意してください。
Full Copyright Statement
完全な著作権声明
Copyright (C) The Internet Society (2000). All Rights Reserved.
Copyright（c）The Internet Society（2000）。無断転載を禁じます。
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
このドキュメントと翻訳は他の人にコピーされて提供される場合があります。また、それについてコメントまたは説明する派生作品、またはその実装を支援することは、いかなる種類の制限なしに、準備、コピー、公開、および部分的に配布される場合があります。、上記の著作権通知とこの段落がそのようなすべてのコピーとデリバティブ作品に含まれている場合。ただし、このドキュメント自体は、インターネット協会や他のインターネット組織への著作権通知や参照を削除するなど、いかなる方法でも変更できない場合があります。インターネット標準プロセスに従うか、英語以外の言語に翻訳するために必要な場合に従う必要があります。
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.
上記の限られた許可は永続的であり、インターネット社会またはその後継者または譲受人によって取り消されることはありません。
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
このドキュメントと本書に含まれる情報は、「現状」に基づいて提供されており、インターネット社会とインターネットエンジニアリングタスクフォースは、ここにある情報の使用が行われないという保証を含むがこれらに限定されないすべての保証を否認します。特定の目的に対する商品性または適合性の権利または黙示的な保証を侵害します。
Acknowledgement
謝辞
Funding for the RFC Editor function is currently provided by the Internet Society.
RFCエディター機能の資金は現在、インターネット協会によって提供されています。