d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Use better manuals for these ntp system calls. These were replaced by

Browse Source 
the netbsd versions, and tweaked by me with suggestions from phk.

Reviewed by: phk
Approved by: re@
This commit is contained in:
Warner Losh 2007-09-15 14:33:55 +00:00
parent dce5df0dfc
commit 09fd542e60
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=172185
3 changed files with 259 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
lib/libc/sys/Makefile.inc
View File

@ -78,7 +78,7 @@ MAN+= _exit.2 abort2.2 accept.2 access.2 acct.2 adjtime.2 \
mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 mprotect.2 \
mq_close.2 mq_getattr.2 mq_notify.2 mq_open.2 mq_receive.2 mq_send.2 \
mq_setattr.2 \
msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \
msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 \
nfssvc.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 rfork.2 rmdir.2 \
rtprio.2 select.2 semctl.2 semget.2 semop.2 send.2 sendfile.2 \
@ -143,6 +143,7 @@ MLINKS+=modnext.2 modfnext.2
MLINKS+=mount.2 nmount.2 mount.2 unmount.2
MLINKS+=mq_send.2 mq_timedsend.2
MLINKS+=mq_receive.2 mq_timedreceive.2
MLINKS+=ntp_adjtime.2 ntp_gettime.2
MLINKS+=pathconf.2 fpathconf.2
MLINKS+=read.2 pread.2 read.2 readv.2 read.2 preadv.2
MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2

342
lib/libc/sys/ntp_adjtime.2
View File

@ -1,7 +1,11 @@
.\" $NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $
.\"
.\" Copyright (c) 2003 Tom Rhodes
.\" 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:
@ -10,6 +14,13 @@
.\" 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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
@ -25,114 +36,263 @@
.\"
.\" $FreeBSD$
.\"
.Dd April 1, 2003
.Dd July 13, 2005
.Dt NTP_ADJTIME 2
.Os
.Sh NAME
.Nm ntp_adjtime
.Nd NTP daemon application interface
.Nm ntp_adjtime ,
.Nm ntp_gettime
.Nd Network Time Protocol (NTP) daemon interface system calls
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In sys/timex.h
.Ft int
.Fn ntp_adjtime "struct timex *tp"
.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 kernel interface to the Network Time Protocol (NTP) daemon
.Xr ntpd 8 .
.Pp
The
.Fn ntp_adjtime
system call is used as a kernel interface
for the Network Time Protocol daemon,
.Xr ntpd 8 .
Certain fields of the
.Vt timex
structure are interpreted in either
microseconds or nanoseconds, according to the state of the
.Dv STA_NANO
bit in the
.Va status
word.
.Pp
In the
.Fx
kernel, the
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
and
.Xr ntp_gettime 2
system calls can be used to determine which
resolution is in use, and to select either one at any time.
The resolution selected affects the scaling of certain fields in the
are used by
.Fn hardclock
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
and
.Fn ntp_adjtime
system calls.
function provides the time, maximum error (sync distance) and
estimated error (dispersion) to client user application programs.
.Pp
Take note that this
.Tn API
is extremely complex and stateful.
Users should not attempt modification without first
reviewing the
.Xr ntpd 8
sources in depth.
In the following, all variables that refer PPS are only relevant if
the
.Em PPS_SYNC
option is enabled in the kernel.
.Pp
.Fn ntp_adjtime
has as argument a
.Va struct timex *
of the following form:
.Bd -literal
/*
* NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock
* oscillator and determine status.
*
* Note: The offset, precision and jitter members are in microseconds if
* STA_NANO is zero and nanoseconds if not.
*/
struct timex {
unsigned int modes; /* clock mode bits (wo) */
long offset; /* time offset (ns/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; /* poll interval (log2 s) (rw) */
long precision; /* clock precision (ns/us) (ro) */
long tolerance; /* clock frequency tolerance (scaled
* PPM) (ro) */
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. They are included in all configurations to insure
* portability.
* kernel.
*/
long ppsfreq; /* PPS frequency (scaled PPM) (ro) */
long jitter; /* PPS jitter (ns/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) */
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
Upon successful completion,
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
will fill the
.Fa tp
argument with the current clock state.
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
Upon successful completion the clock state is returned.
Otherwise a -1 is returned and the global variable
.Va errno
is set to indicate the error.
.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
if the user calling
.Fn ntp_adjtime
does not have sufficient permissions.
.Pp
Possible states of the clock are:
.Pp
.Bl -tag -compact -width ".Dv TIME_ERROR"
.It Dv TIME_OK
.Bl -tag -width TIME_ERROR -compact -offset indent
.It TIME_OK
Everything okay, no leap second warning.
.It Dv TIME_INS
insert leap second warning.
.It Dv TIME_DEL
delete leap second warning.
.It Dv TIME_OOP
.It TIME_INS
.Dq insert leap second
warning.
At the end of the day, a leap second will be inserted after 23:59:59.
.It TIME_DEL
.Dq delete leap second
warning.
At the end of the day, second 23:59:59 will be skipped.
.It TIME_OOP
Leap second in progress.
.It Dv TIME_WAIT
Leap second has occurred.
.It Dv TIME_ERROR
.It TIME_WAIT
Leap second has occurred within the last few seconds..
.It TIME_ERROR
Clock not synchronized.
.El
.Sh ERRORS
@ -143,8 +303,20 @@ system call may return
if the caller
does not have sufficient permissions.
.Sh SEE ALSO
.Xr ntp_gettime 2 ,
.Xr options 4 ,
.Xr ntpd 8 ,
.Xr hardclock 9 ,
.Xr hz 9
.Bl -tag -width indent
.It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
.It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm
.It Pa ftp://time.nist.gov/pub/leap-seconds.list
.El
.Sh BUGS
Take note that this
.Tn API
is extremely complex and stateful.
Users should not attempt modification without first
reviewing the
.Xr ntpd 8
.Sh AUTHORS
This manual page was written by
.An Tom Rhodes Aq trhodes@FreeBSD.org .
sources in depth.

116
lib/libc/sys/ntp_gettime.2
View File

@ -1,116 +0,0 @@
.\"
.\" Copyright (c) 2003 Tom Rhodes
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD$
.\"
.Dd June 21, 2003
.Dt NTP_GETTIME 2
.Os
.Sh NAME
.Nm ntp_gettime
.Nd NTP user application interface
.Sh SYNOPSIS
.In sys/timex.h
.Ft int
.Fn ntp_gettime "struct ntptimeval *ntv"
.Sh DESCRIPTION
The time returned by
.Fn ntp_gettime
is in a
.Vt timespec
structure, but may be in either microsecond
(seconds and microseconds) or nanosecond (seconds and nanoseconds) format.
The particular format in use is determined by the
.Dv STA_NANO
bit of the status
word returned by the
.Fn ntp_adjtime
system call.
.Fn ntp_gettime
has as argument a pointer to the
.Vt ntptimeval
structure with the following members:
.Bd -literal
struct ntptimeval {
struct timespec time; /* current time (ns) (ro) */
long maxerror; /* maximum error (us) (ro) */
long esterror; /* estimated error (us) (ro) */
long tai; /* TAI-UTC offset */
int time_state; /* time status */
};
.Ed
.Pp
These are understood as:
.Bl -tag -width ".Va time_state"
.It Va time
Current time (read-only).
.It Va maxerror
Maximum error in microseconds (read-only).
.It Va esterror
Estimated error in microseconds (read-only).
.It Va tai
Offset in seconds between the TAI and UTC time scales.
This offset is published twice a year and is an integral number of
seconds between TAI (which does not have leap seconds) and UTC (which
does).
.Xr ntpd 8
or some other agent maintains this value.
A value of 0 means unknown.
As of the date of the manual page, the offset is 32 seconds.
.It Va time_state
Current time status.
.El
.Sh RETURN VALUES
.Rv -std ntp_gettime
.Pp
Possible states of the clock are:
.Pp
.Bl -tag -compact -width ".Dv TIME_ERROR"
.It Dv TIME_OK
Everything okay, no leap second warning.
.It Dv TIME_INS
Positive leap second warning.
At the end of the day, an additional second will be inserted after 23:59:59.
.It Dv TIME_DEL
Negative leap second warning.
At the end of the day, 23:59:59 is skipped.
.It Dv TIME_OOP
Leap second in progress.
.It Dv TIME_WAIT
Leap second has occurred.
.It Dv TIME_ERROR
Clock not synchronized.
.El
.Sh SEE ALSO
.Xr ntp_adjtime 2 ,
.Xr ntpd 8
.Bl -tag -width indent
.It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
.It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm
.It Pa ftp://time.nist.gov/pub/leap-seconds.list
.El
.Sh AUTHORS
This manual page was written by
.An Tom Rhodes Aq trhodes@FreeBSD.org .