[src/trunk]: src/lib/libc/sys Add ntp_adjtime(2) and ntp_gettime(2) man page.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/31b3d0d5d060
branches:  trunk
changeset: 514588:31b3d0d5d060
user:      wiz <wiz%NetBSD.org@localhost>
date:      Thu Sep 06 00:18:18 2001 +0000

description:
Add ntp_adjtime(2) and ntp_gettime(2) man page.

diffstat:

 lib/libc/sys/Makefile.inc  |    5 +-
 lib/libc/sys/ntp_adjtime.2 |  296 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 299 insertions(+), 2 deletions(-)

diffs (truncated from 326 to 300 lines):

diff -r a03ae7b5f20e -r 31b3d0d5d060 lib/libc/sys/Makefile.inc
--- a/lib/libc/sys/Makefile.inc Wed Sep 05 23:53:22 2001 +0000
+++ b/lib/libc/sys/Makefile.inc Thu Sep 06 00:18:18 2001 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.113 2001/07/18 23:03:10 thorpej Exp $
+#      $NetBSD: Makefile.inc,v 1.114 2001/09/06 00:18:18 wiz Exp $
 #      @(#)Makefile.inc        8.3 (Berkeley) 10/24/94
 
 # sys sources
@@ -199,7 +199,7 @@
        link.2 listen.2 lseek.2 mkdir.2 mkfifo.2 mknod.2 \
        madvise.2 mincore.2 minherit.2 mlock.2 mlockall.2 mmap.2 mount.2 \
        mprotect.2 msgctl.2 msgget.2 msgrcv.2 msgsnd.2 msync.2 \
-       munmap.2 nanosleep.2 nfssvc.2 open.2 pathconf.2 pipe.2 \
+       munmap.2 nanosleep.2 nfssvc.2 ntp_adjtime.2 open.2 pathconf.2 pipe.2 \
        poll.2 profil.2 ptrace.2 quotactl.2 read.2 readlink.2 \
        reboot.2 recv.2 rename.2 revoke.2 rmdir.2 select.2 semctl.2 \
        semget.2 semop.2 send.2 setgroups.2 setpgid.2 setregid.2 \
@@ -237,6 +237,7 @@
 MLINKS+=mlock.2 munlock.2
 MLINKS+=mlockall.2 munlockall.2
 MLINKS+=mount.2 unmount.2
+MLINKS+=ntp_adjtime.2 ntp_gettime.2
 MLINKS+=pathconf.2 fpathconf.2
 MLINKS+=read.2 readv.2 read.2 pread.2 read.2 preadv.2
 MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2
diff -r a03ae7b5f20e -r 31b3d0d5d060 lib/libc/sys/ntp_adjtime.2
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/sys/ntp_adjtime.2        Thu Sep 06 00:18:18 2001 +0000
@@ -0,0 +1,296 @@
+.\"    $NetBSD: ntp_adjtime.2,v 1.1 2001/09/06 00:18:18 wiz Exp $
+.\"
+.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Thomas Klausner.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 4, 2001
+.Dt NTP_ADJTIME 2
+.Os
+.Sh NAME
+.Nm ntp_adjtime ,
+.Nm ntp_gettime
+.Nd Network Time Protocol (NTP) daemon interface system calls
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.Fd #include <sys/timex.h>
+.Ft int
+.Fn ntp_adjtime "struct timex *"
+.Ft int
+.Fn ntp_gettime "struct ntptimeval *"
+.Sh DESCRIPTION
+The two system calls
+.Fn ntp_adjtime
+and
+.Fn ntp_gettime
+are the interface to the Network Time Protocol (NTP) daemon
+.Xr ntpd 8 .
+.Pp
+The
+.Fn ntp_adjtime
+function is used by the NTP daemon to adjust the system clock to an
+externally derived time.  The time offset and related variables which
+are set by
+.Fn ntp_adjtime
+are used by
+.Xr hardclock 9
+to adjust the phase and frequency of the phase- or frequency-lock loop
+(PLL resp. FLL) which controls the system clock.
+.Pp
+The
+.Fn ntp_gettime
+function provides the time, maximum error (sync distance) and
+estimated error (dispersion) to client user application programs.
+.Pp
+In the following, all variables that refer PPS are only relevant if
+the
+.Em PPS_SYNC
+option (see
+.Xr options 4 )
+is enabled in the kernel.
+.Pp
+.Fn ntp_adjtime
+has as argument a
+.Va struct timex *
+of the following form:
+.Bd -literal
+struct timex {
+       unsigned int modes;     /* clock mode bits (wo) */
+       long offset;            /* time offset (us) (rw) */
+       long freq;              /* frequency offset (scaled ppm) (rw) */
+       long maxerror;          /* maximum error (us) (rw) */
+       long esterror;          /* estimated error (us) (rw) */
+       int status;             /* clock status bits (rw) */
+       long constant;          /* pll time constant (rw) */
+       long precision;         /* clock precision (us) (ro) */
+       long tolerance;         /* clock frequency tolerance (scaled
+                                * ppm) (ro) */
+       /*
+        * The following read-only structure members are implemented
+        * only if the PPS signal discipline is configured in the
+        * kernel.
+        */
+       long ppsfreq;           /* pps frequency (scaled ppm) (ro) */
+       long jitter;            /* pps jitter (us) (ro) */
+       int shift;              /* interval duration (s) (shift) (ro) */
+       long stabil;            /* pps stability (scaled ppm) (ro) */
+       long jitcnt;            /* jitter limit exceeded (ro) */
+       long calcnt;            /* calibration intervals (ro) */
+       long errcnt;            /* calibration errors (ro) */
+       long stbcnt;            /* stability limit exceeded (ro) */
+};
+.Ed
+.Pp
+The members of this struct have the following meanings when used as
+argument for
+.Fn ntp_adjtime :
+.Bl -tag -width tolerance -compact
+.It Fa modes
+Defines what settings should be changed with the current
+.Fn ntp_adjtime
+call (write-only).  Bitwise OR of the following:
+.Bl -tag -width MOD_TIMECONST -compact -offset indent
+.It MOD_OFFSET
+set time offset
+.It MOD_FREQUENCY
+set frequency offset
+.It MOD_MAXERROR
+set maximum time error
+.It MOD_ESTERROR
+set estimated time error
+.It MOD_STATUS
+set clock status bits
+.It MOD_TIMECONST
+set PLL time constant
+.It MOD_CLKA
+set clock A
+.It MOD_CLKB
+set clock B
+.El
+.It Fa offset
+Time offset (in microseconds), used by the PLL/FLL to adjust the
+system time in small increments (read-write).
+.It Fa freq
+Frequency offset (scaled ppm) (read-write).
+.It Fa maxerror
+Maximum error (in microseconds).  Initialized by an
+.Fn ntp_adjtime
+call, and increased by the kernel once each second to reflect the maximum
+error bound growth (read-write).
+.It Fa esterror
+Estimated error (in microseconds).  Set and read by
+.Fn ntp_adjtime ,
+but unused by the kernel (read-write).
+.It Fa status
+System clock status bits (read-write). Bitwise OR of the following:
+.Bl -tag -width STA_PPSJITTER -compact -offset indent
+.It STA_PLL
+Enable PLL updates (read-write).
+.It STA_PPSFREQ
+Enable PPS freq discipline (read-write).
+.It STA_PPSTIME
+Enable PPS time discipline (read-write).
+.It STA_FLL
+Select frequency-lock mode (read-write).
+.It STA_INS
+Insert leap (read-write).
+.It STA_DEL
+Delete leap (read-write).
+.It STA_UNSYNC
+Clock unsynchronized (read-write).
+.It STA_FREQHOLD
+Hold frequency (read-write).
+.It STA_PPSSIGNAL
+PPS signal present (read-only).
+.It STA_PPSJITTER
+PPS signal jitter exceeded (read-only).
+.It STA_PPSWANDER
+PPS signal wander exceeded (read-only).
+.It STA_PPSERROR
+PPS signal calibration error (read-only).
+.It STA_CLOCKERR
+Clock hardware fault (read-only).
+.El
+.It Fa constant
+PLL time constant, determines the bandwidth, or
+.Dq stiffness ,
+of the PLL (read-write).
+.It Fa precision
+Clock precision (in microseconds).  In most cases the same
+as the kernel tick variable.
+.\" (see
+.\" .Xr hz 9 )
+If a precision clock counter or external time-keeping signal is available,
+it could be much lower (and depend on the state of the signal)
+(read-only).
+.It Fa tolerance
+Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
+ppm).  Ordinarily a property of the architecture, but could change under
+the influence of external time-keeping signals (read-only).
+.It Fa ppsfreq
+PPS frequency offset produced by the frequency median filter (scaled
+ppm) (read-only).
+.It Fa jitter
+PPS jitter measured by the time median filter in microseconds
+(read-only).
+.It Fa shift
+Logarithm to base 2 of the interval duration in seconds (PPS,
+read-only).
+.It Fa stabil
+PPS stability (scaled ppm); dispersion (wander) measured by the
+frequency median filter (read-only).
+.It Fa jitcnt
+Number of seconds that have been discarded because the jitter measured
+by the time median filter exceeded the limit
+.Em MAXTIME
+(PPS, read-only).
+.It Fa calcnt
+Count of calibration intervals (PPS, read-only).
+.It Fa errcnt
+Number of calibration intervals that have been discarded because the
+wander exceeded the limit
+.Em MAXFREQ
+or where the calibration interval jitter exceeded two ticks (PPS,
+read-only).
+.It Fa stbcnt
+Number of calibration intervals that have been discarded because the
+frequency wander exceeded the limit
+.Em MAXFREQ Ns /4
+(PPS, read-only).
+.El
+After the
+.Fn ntp_adjtime
+call, the
+.Va struct timex *
+structure contains the current values of the corresponding variables.
+.Pp
+.Fn ntp_gettime
+has as argument a
+.Va struct ntptimeval *
+with the following members:
+.Bd -literal
+struct ntptimeval {
+       struct timeval time;    /* current time (ro) */
+       long maxerror;          /* maximum error (us) (ro) */
+       long esterror;          /* estimated error (us) (ro) */
+};
+.Ed
+.Pp
+These have the following meaning:
+.Bl -tag -width tolerance -compact
+.It Fa time
+Current time (read-only).
+.It Fa maxerror
+Maximum error in microseconds (read-only).
+.It Fa esterror
+Estimated error in microseconds (read-only).
+.El
+.Sh RETURN VALUES
+.Fn ntp_adjtime
+and
+.Fn ntp_gettime
+return the current state of the clock on success, or any of the errors
+of
+.Xr copyin 9
+and
+.Xr copyout 9 .
+.Fn ntp_adjtime
+may additionally return
+.Er EPERM