Bring kernel time variable and access function docs up to date by
updating the list of variables and mentioning the bin(up)time functions.
This commit is contained in:
brooks
parent
71fbe6ccac
commit
55525729a1
@ -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 \
|
||||
|
||||
@ -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 .
|
||||
|
||||
@ -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 binuptime
|
||||
and
|
||||
.Fn getbinuptime
|
||||
functions store the time elapsed since boot as a
|
||||
.Ft struct bintime
|
||||
at the address specified by
|
||||
.Fa bt .
|
||||
The
|
||||
.Fn microuptime
|
||||
and
|
||||
.Fn getmicrouptime
|
||||
functions store the time elapsed since boot as a
|
||||
functions perform the same utility, but record the elapsed time as a
|
||||
.Ft struct timeval
|
||||
at the address specified by
|
||||
.Fa tv .
|
||||
The
|
||||
instead.
|
||||
Similarly the
|
||||
.Fn nanouptime
|
||||
and
|
||||
.Fn getnanouptime
|
||||
functions perform the same utility, but record the elapsed time as a
|
||||
.Ft struct timespec
|
||||
instead.
|
||||
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 ,
|
||||
|
||||
@ -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
|
||||
.Xr binuptime 9,
|
||||
.Xr getbinuptime 9 ,
|
||||
.Xr microuptime 9 ,
|
||||
.Xr getmicrouptime 9 ,
|
||||
.Xr nanouptime 9 ,
|
||||
and
|
||||
.Xr getnanouptime 9 ,
|
||||
functions can be used to get the time elapse since boot more accurately
|
||||
and in an atomic manner.
|
||||
The
|
||||
.Va boottime
|
||||
and
|
||||
.Va runtime
|
||||
variables may be read and written without special precautions.
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user