Bring kernel time variable and access function docs up to date by

updating the list of variables and mentioning the bin(up)time functions.

4 files changed, 130 insertions, 110 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index ee6a34e..aa1e80d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -609,10 +609,14 @@ MLINKS+=mdchain.9 md_append_record.9 \
 	mdchain.9 md_get_uio.9 \
 	mdchain.9 md_initm.9 \
 	mdchain.9 md_next_record.9
-MLINKS+=microtime.9 getmicrotime.9 \
+MLINKS+=microtime.9 bintime.9 \
+	microtime.9 getbintime.9 \
+	microtime.9 getmicrotime.9 \
 	microtime.9 getnanotime.9 \
 	microtime.9 nanotime.9
-MLINKS+=microuptime.9 getmicrouptime.9 \
+MLINKS+=microuptime.9 binuptime.9 \
+	microuptime.9 getbinuptime.9 \
+	microuptime.9 getmicrouptime.9 \
 	microuptime.9 getnanouptime.9 \
 	microuptime.9 nanouptime.9
 MLINKS+=mi_switch.9 cpu_switch.9 \
@@ -854,8 +858,8 @@ MLINKS+=taskqueue.9 TASK_INIT.9 \
 	taskqueue.9 taskqueue_free.9 \
 	taskqueue.9 taskqueue_run.9
 MLINKS+=time.9 boottime.9 \
-	time.9 mono_time.9 \
-	time.9 runtime.9
+	time.9 time_second.9 \
+	time.9 time_uptime.9
 MLINKS+=timeout.9 callout_drain.9 \
 	timeout.9 callout_handle_init.9 \
 	timeout.9 callout_init.9 \
diff --git a/share/man/man9/microtime.9 b/share/man/man9/microtime.9
index 7783c32..7926dba 100644
--- a/share/man/man9/microtime.9
+++ b/share/man/man9/microtime.9
@@ -24,10 +24,12 @@
 .\"
 .\"    $FreeBSD$
 .\"
-.Dd January 3, 2000
+.Dd September 16, 2004
 .Dt MICROTIME 9
 .Os
 .Sh NAME
+.Nm bintime ,
+.Nm getbintime ,
 .Nm microtime ,
 .Nm getmicrotime ,
 .Nm nanotime ,
@@ -36,6 +38,10 @@
 .Sh SYNOPSIS
 .In sys/time.h
 .Ft void
+.Fn bintime "struct bintime *bt"
+.Ft void
+.Fn getbintime "struct bintime *bt"
+.Ft void
 .Fn microtime "struct timeval *tv"
 .Ft void
 .Fn getmicrotime "struct timeval *tv"
@@ -45,40 +51,51 @@
 .Fn getnanotime "struct timespec *tsp"
 .Sh DESCRIPTION
 The
+.Fn bintime
+and
+.Fn getbintime
+functions store the system time as a
+.Ft struct bintime
+at the addresses specified by
+.Fa bt .
+The
 .Fn microtime
 and
 .Fn getmicrotime
-functions store the system time as a
+functions perform the same utility, but record the time as a
 .Ft struct timeval
-at the address specified by
-.Fa tv .
-The
+instead.
+Similarly the
 .Fn nanotime
 and
 .Fn getnanotime
-functions perform the same utility, but record the time as a
-.Ft struct timespec
-instead.
+functions store the time as a
+.Ft struct timespec .
 .Pp
-.Fn Microtime
+.Fn Bintime ,
+.Fn microtime ,
 and
 .Fn nanotime
 always query the timecounter to return the current time as precisely as
 possible.
 Whereas
-.Fn getmicrotime
+.Fn getbintime ,
+.Fn getmicrotime ,
 and
 .Fn getnanotime
 functions are abstractions which return a less precise, but
 faster to obtain, time.
 .Pp
 The intent of the
-.Fn getmicrotime
+.Fn getbintime ,
+.Fn getmicrotime ,
 and
 .Fn getnanotime
 functions is to enforce the user's preference for timer accuracy versus
 execution time.
 .Sh SEE ALSO
+.Xr binuptime 9 ,
+.Xr getbinuptime 9 ,
 .Xr getmicrouptime 9 ,
 .Xr getnanouptime 9 ,
 .Xr microuptime 9 ,
@@ -86,13 +103,17 @@ execution time.
 .Xr tvtohz 9
 .Sh HISTORY
 The
+.Nm bintime
+functions first appeared in
+.Fx 5.0 .
+The
 .Nm
 and
 .Nm nanotime
 functions first appeared in
 .Fx 3.0
 but existed in other incarnations since
-.Bx 4.4
+.Bx 4.4 .
 .Sh AUTHORS
 This manual page was written by
 .An Kelly Yancey Aq kbyanc@posi.net .
diff --git a/share/man/man9/microuptime.9 b/share/man/man9/microuptime.9
index 304f205..3e0b6ac 100644
--- a/share/man/man9/microuptime.9
+++ b/share/man/man9/microuptime.9
@@ -24,10 +24,12 @@
 .\"
 .\"    $FreeBSD$
 .\"
-.Dd January 3, 2000
+.Dd September, 16 2004
 .Dt MICROUPTIME 9
 .Os
 .Sh NAME
+.Nm binuptime ,
+.Nm getbinuptime ,
 .Nm microuptime ,
 .Nm getmicrouptime ,
 .Nm nanouptime ,
@@ -36,6 +38,10 @@
 .Sh SYNOPSIS
 .In sys/time.h
 .Ft void
+.Fn binuptime "struct bintime *bt"
+.Ft void
+.Fn getbinuptime "struct bintime *bt"
+.Ft void
 .Fn microuptime "struct timeval *tv"
 .Ft void
 .Fn getmicrouptime "struct timeval *tv"
@@ -45,40 +51,51 @@
 .Fn getnanouptime "struct timespec *tsp"
 .Sh DESCRIPTION
 The
-.Fn microuptime
+.Fn binuptime
 and
-.Fn getmicrouptime
+.Fn getbinuptime
 functions store the time elapsed since boot as a
-.Ft struct timeval
+.Ft struct bintime
 at the address specified by
-.Fa tv .
+.Fa bt .
 The
-.Fn nanouptime
+.Fn microuptime
 and
-.Fn getnanouptime
+.Fn getmicrouptime
 functions perform the same utility, but record the elapsed time as a
-.Ft struct timespec
+.Ft struct timeval
 instead.
+Similarly the
+.Fn nanouptime
+and
+.Fn getnanouptime
+functions store the elapsed time as a
+.Ft struct timespec .
 .Pp
-.Fn Microuptime
+.Fn Binuptime ,
+.Fn microuptime ,
 and
 .Fn nanouptime
 always query the timecounter to return the current time as precisely as
 possible.
 Whereas
-.Fn getmicrouptime
+.Fn getbinuptime ,
+.Fn getmicrouptime ,
 and
 .Fn getnanouptime
 functions are abstractions which return a less precise, but
 faster to obtain, time.
 .Pp
 The intent of the
-.Fn getmicrouptime
+.Fn getbinuptime ,
+.Fn getmicrouptime ,
 and
 .Fn getnanouptime
 functions is to enforce the user's preference for timer accuracy versus
 execution time.
 .Sh SEE ALSO
+.Xr bintime 9 ,
+.Xr getbintime 9 ,
 .Xr getmicrotime 9 ,
 .Xr getnanotime 9 ,
 .Xr microtime 9 ,
diff --git a/share/man/man9/time.9 b/share/man/man9/time.9
index a5bf973..8153a86 100644
--- a/share/man/man9/time.9
+++ b/share/man/man9/time.9
@@ -31,113 +31,91 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 22, 1997
+.Dd September 17, 2004
 .Dt TIME 9
 .Os
 .Sh NAME
+.In sys/time.h
 .Nm boottime ,
-.Nm mono_time ,
-.Nm runtime ,
-.Nm time
+.Nm time_second ,
+.Nm time_uptime
 .Nd system time variables
 .Sh SYNOPSIS
 .Bl -item -compact
 .It
 .Va extern struct timeval boottime ;
 .It
-.Va extern volatile struct timeval mono_time ;
+.Va extern struct time_t time_second ;
 .It
-.Va extern struct timeval runtime ;
-.It
-.Va extern struct timeval time ;
+.Va extern struct timeval time_uptime ;
 .El
 .Sh DESCRIPTION
 The
-.Va time
-variable is the system's
-.Dq wall time
-clock.
-It is set at boot by
-.Xr inittodr 9 ,
-and is updated by the
-.Xr settimeofday 2
-system call and by periodic clock interrupts.
-.Pp
-The
 .Va boottime
 variable holds the system boot time.
-It is set from
-.Va time
-at system boot, and is updated when the system time is adjusted
-with
-.Xr settimeofday 2 .
 .Pp
 The
-.Va runtime
-variable holds the time that the system switched to the
-current process.
-It is set after each context switch,
-and is updated when the system time is adjusted with
-.Xr settimeofday 2 .
-Because
-.Va runtime
-is used for system accounting, it is set with the high-resolution
-.Xr microtime 9
-function, rather than being copied from
-.Va time .
+.Va time_second
+variable is the system's
+.Dq wall time
+clock to the second.
 .Pp
 The
-.Va mono_time
-variable is a monotonically increasing system clock.
-It is set
-from
-.Va time
-at boot, and is updated by the periodic timer interrupt.
-(It is
-not updated by
-.Xr settimeofday 2 . )
+.Va time_uptime variable is the number of seconds since boot.
 .Pp
-All of these variables contain times
-expressed in seconds and microseconds since midnight (0 hour),
-January 1, 1970.
-.Pp
-Clock interrupts should be blocked
-when reading or writing
-.Va time
-or
-.Va mono_time ,
-because those variables are updated by
-.Fn hardclock .
 The
-.Xr gettime 9
-function can be used to read the
-.Va time
-variable in an atomic manner.
-There is no equivalent function for accessing
-.Va mono_time .
+.Xr bintime 9,
+.Xr getbintime 9 ,
+.Xr microtime 9 ,
+.Xr getmicrotime 9 ,
+.Xr nanotime 9 ,
+and
+.Xr getnanotime 9 ,
+functions can be used to get the current time more accurately and in an
+atomic manner.
+Similarly, the
 The
-.Va boottime
+.Xr binuptime 9,
+.Xr getbinuptime 9 ,
+.Xr microuptime 9 ,
+.Xr getmicrouptime 9 ,
+.Xr nanouptime 9 ,
 and
-.Va runtime
-variables may be read and written without special precautions.
+.Xr getnanouptime 9 ,
+functions can be used to get the time elapse since boot more accurately
+and in an atomic manner.
+The
+.Va boottime
+variable may be read and written without special precautions.
 .Pp
-It should be noted that due to the differences in how the time values
-returned by
-.Xr gettime 9
-and
-.Xr microtime 9
-are updated, comparing the results of the two routines
-may result in a time value that appears to go backwards.
-This can be avoided by consistently using one function or the other
-for use in any given context.
 .Sh SEE ALSO
+.Xr clock_settime 2 ,
+.Xr ntp_adjtime 2 ,
 .Xr settimeofday 2 ,
-.Xr gettime 9 ,
-.\" .Xr hardclock 9 ,
-.\" .Xr hz 9 ,
-.Xr inittodr 9 ,
-.Xr microtime 9
-.Sh BUGS
-The notion of having a single
-.Va runtime
-variable obviously would not be appropriate in multiprocessor systems.
+.Xr getbintime 9 ,
+.Xr getbinuptime 9 ,
+.Xr getmicrotime 9 ,
+.Xr getmicrouptime 9 ,
+.Xr getnanotime 9 ,
+.Xr getnanouptime 9 ,
+.Xr bintime 9 ,
+.Xr binuptime 9 ,
+.Xr microtime 9 ,
+.Xr microuptime 9 ,
+.Xr nanotime 9,
+.Xr nanouptime 9
+.Rs
+.%A "Poul-Henning Kamp"
+.%T "Timecounters: Efficient and precise timekeeping in SMP kernels"
+.%J "Proceedings of EuroBSDCon 2002"
+.%C "Amsterdam"
+.%O /usr/share/doc/papers/timecounter.ascii.gz
+.Re
+.Rs
+.%A "Marshall Kirk McKusick"
+.%A "George V. Neville-Neil"
+.%B "The Design and Implementation of the FreeBSD Operating System"
+.%D "July 2004"
+.%I "Addison-Wesley"
+.%P "57-61,65-66"
+.Re