diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index e84b06f940f7..75ffcfcc3da6 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,171 +1,172 @@ # @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 # $FreeBSD$ # sys sources .PATH: ${.CURDIR}/${MACHINE_ARCH}/sys ${.CURDIR}/sys # Include the generated makefile containing the *complete* list # of syscall names in MIASM. .include "${.CURDIR}/../../sys/sys/syscall.mk" # Include machine dependent definitions. # # MDASM names override the default syscall names in MIASM. # NOASM will prevent the default syscall code from being generated. # .if exists(${.CURDIR}/${MACHINE_ARCH}/sys/Makefile.inc) .include "${.CURDIR}/${MACHINE_ARCH}/sys/Makefile.inc" .endif # Sources common to both syscall interfaces: SRCS+= stack_protector.c __error.c .if !defined(WITHOUT_SYSCALL_COMPAT) SRCS+= ftruncate.c lseek.c mmap.c pread.c pwrite.c truncate.c .endif # Add machine dependent asm sources: SRCS+=${MDASM} # Look though the complete list of syscalls (MIASM) for names that are # not defined with machine dependent implementations (MDASM) and are # not declared for no generation of default code (NOASM). Add each # syscall that satisfies these conditions to the ASM list. .for _asm in ${MIASM} .if (${MDASM:R:M${_asm:R}} == "") .if (${NOASM:R:M${_asm:R}} == "") ASM+=$(_asm) .endif .endif .endfor OBJS+= ${ASM} ${PSEUDO} SASM= ${ASM:S/.o/.S/} SPSEUDO= ${PSEUDO:S/.o/.S/} SRCS+= ${SASM} ${SPSEUDO} SYM_MAPS+= ${.CURDIR}/sys/Symbol.map # Generated files CLEANFILES+= ${SASM} ${SPSEUDO} ${SASM}: printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' > ${.TARGET} ${SPSEUDO}: printf '#include "SYS.h"\nPSEUDO(${.PREFIX:S/_//})\n' \ > ${.TARGET} MAN+= _exit.2 abort2.2 accept.2 access.2 acct.2 adjtime.2 \ aio_cancel.2 aio_error.2 aio_read.2 aio_return.2 \ aio_suspend.2 aio_waitcomplete.2 aio_write.2 \ bind.2 brk.2 chdir.2 chflags.2 \ chmod.2 chown.2 chroot.2 clock_gettime.2 close.2 \ connect.2 dup.2 execve.2 extattr_get_file.2 \ fcntl.2 fhopen.2 flock.2 fork.2 fsync.2 \ getdirentries.2 getdtablesize.2 \ getfh.2 getfsstat.2 getgid.2 getgroups.2 getitimer.2 getlogin.2 \ getpeername.2 getpgrp.2 getpid.2 getpriority.2 getrlimit.2 \ getrusage.2 getsid.2 getsockname.2 \ getsockopt.2 gettimeofday.2 getuid.2 \ intro.2 ioctl.2 issetugid.2 jail.2 kenv.2 kill.2 \ kldfind.2 kldfirstmod.2 kldload.2 kldnext.2 kldstat.2 kldsym.2 \ kldunload.2 kqueue.2 kse.2 ktrace.2 link.2 lio_listio.2 listen.2 \ lseek.2 \ madvise.2 mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.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 \ setgroups.2 setpgid.2 setregid.2 setresuid.2 setreuid.2 setsid.2 \ setuid.2 shmat.2 shmctl.2 shmget.2 shutdown.2 \ sigaction.2 sigaltstack.2 sigpending.2 sigprocmask.2 sigqueue.2 \ sigreturn.2 sigstack.2 sigsuspend.2 sigwait.2 sigwaitinfo.2 \ socket.2 socketpair.2 stat.2 statfs.2 \ sctp_generic_recvmsg.2 sctp_generic_sendmsg.2 sctp_peeloff.2 \ swapon.2 symlink.2 sync.2 sysarch.2 syscall.2 \ timer_create.2 timer_delete.2 timer_settime.2 \ truncate.2 umask.2 undelete.2 \ unlink.2 utimes.2 utrace.2 uuidgen.2 vfork.2 wait.2 write.2 .if !defined(NO_P1003_1B) MAN+= sched_get_priority_max.2 sched_setparam.2 \ sched_setscheduler.2 sched_yield.2 .endif MLINKS+=access.2 eaccess.2 MLINKS+=brk.2 sbrk.2 MLINKS+=chdir.2 fchdir.2 MLINKS+=chflags.2 fchflags.2 chflags.2 lchflags.2 MLINKS+=chmod.2 fchmod.2 chmod.2 lchmod.2 MLINKS+=chown.2 fchown.2 chown.2 lchown.2 MLINKS+=clock_gettime.2 clock_getres.2 clock_gettime.2 clock_settime.2 MLINKS+=dup.2 dup2.2 MLINKS+=extattr_get_file.2 extattr.2 \ extattr_get_file.2 extattr_delete_fd.2 \ extattr_get_file.2 extattr_delete_file.2 \ extattr_get_file.2 extattr_delete_list.2 \ extattr_get_file.2 extattr_get_fd.2 \ extattr_get_file.2 extattr_get_list.2 \ extattr_get_file.2 extattr_list_fd.2 \ extattr_get_file.2 extattr_list_file.2 \ extattr_get_file.2 extattr_list_link.2 \ extattr_get_file.2 extattr_set_fd.2 \ extattr_get_file.2 extattr_set_file.2 \ extattr_get_file.2 extattr_set_link.2 MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatfs.2 MLINKS+=getdirentries.2 getdents.2 MLINKS+=getfh.2 lgetfh.2 MLINKS+=getgid.2 getegid.2 MLINKS+=getitimer.2 setitimer.2 MLINKS+=getlogin.2 getlogin_r.3 MLINKS+=getlogin.2 setlogin.2 MLINKS+=getpgrp.2 getpgid.2 MLINKS+=getpid.2 getppid.2 MLINKS+=getpriority.2 setpriority.2 MLINKS+=getrlimit.2 setrlimit.2 MLINKS+=getsockopt.2 setsockopt.2 MLINKS+=gettimeofday.2 settimeofday.2 MLINKS+=getuid.2 geteuid.2 MLINKS+=intro.2 errno.2 MLINKS+=jail.2 jail_attach.2 MLINKS+=kqueue.2 kevent.2 MLINKS+=kse.2 kse_create.2 kse.2 kse_exit.2 kse.2 kse_release.2 \ kse.2 kse_switchin.2 kse.2 kse_thr_interrupt.2 kse.2 kse_wakeup.2 MLINKS+=madvise.2 posix_madvise.2 MLINKS+=mlock.2 munlock.2 MLINKS+=mlockall.2 munlockall.2 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 MLINKS+=select.2 FD_CLR.3 select.2 FD_ISSET.3 select.2 FD_SET.3 \ select.2 FD_ZERO.3 MLINKS+=send.2 sendmsg.2 send.2 sendto.2 MLINKS+=setpgid.2 setpgrp.2 MLINKS+=setresuid.2 setresgid.2 setresuid.2 getresuid.2 setresuid.2 getresgid.2 MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 MLINKS+=shmat.2 shmdt.2 MLINKS+=sigwaitinfo.2 sigtimedwait.2 MLINKS+=stat.2 fstat.2 stat.2 lstat.2 MLINKS+=statfs.2 fstatfs.2 MLINKS+=syscall.2 __syscall.2 MLINKS+=swapon.2 swapoff.2 MLINKS+=timer_settime.2 timer_gettime.2 timer_settime.2 timer_getoverrun.2 MLINKS+=truncate.2 ftruncate.2 MLINKS+=utimes.2 futimes.2 utimes.2 lutimes.2 MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 MLINKS+=write.2 pwrite.2 write.2 writev.2 write.2 pwritev.2 .if !defined(NO_P1003_1B) MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \ sched_get_priority_max.2 sched_rr_get_interval.2 MLINKS+=sched_setparam.2 sched_getparam.2 MLINKS+=sched_setscheduler.2 sched_getscheduler.2 .endif diff --git a/lib/libc/sys/ntp_adjtime.2 b/lib/libc/sys/ntp_adjtime.2 index a7bf4f18016d..5f5185f4976c 100644 --- a/lib/libc/sys/ntp_adjtime.2 +++ b/lib/libc/sys/ntp_adjtime.2 @@ -1,150 +1,322 @@ +.\" $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: .\" 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 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 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 +The two system calls .Fn ntp_adjtime -system call is used as a kernel interface -for the Network Time Protocol daemon, +and +.Fn ntp_gettime +are the kernel interface to the Network Time Protocol (NTP) 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 +The .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 -.Fn ntp_gettime -and +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 -system calls. +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 -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. +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 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 +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 -will fill the -.Fa tp -argument with the current clock state. +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 The .Fn ntp_adjtime system call may return .Er EPERM 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. diff --git a/lib/libc/sys/ntp_gettime.2 b/lib/libc/sys/ntp_gettime.2 deleted file mode 100644 index f556d74f2795..000000000000 --- a/lib/libc/sys/ntp_gettime.2 +++ /dev/null @@ -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 .