RFC 2783 (rfc2783) - Page 2 of 31

Pulse-Per-Second API for UNIX-like Operating Systems, Version 1

RFC 2783                  Pulse-Per-Second API                March 2000


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

   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).

   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.



Mogul, et al.                Informational