Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0
RFC 2783

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 05

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

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.

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.

Mogul, et al.                Informational                      [Page 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                      [Page 2]
RFC 2783                  Pulse-Per-Second API                March 2000