freebsd-dev/share/man/man9/microtime.9

.\" Copyright (c) 2000 Kelly Yancey
.\" 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 September 16, 2004
.Dt MICROTIME 9
.Os
.Sh NAME
.Nm bintime ,
.Nm getbintime ,
.Nm microtime ,
.Nm getmicrotime ,
.Nm nanotime ,
.Nm getnanotime
.Nd get the current time
.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"
.Ft void
.Fn nanotime "struct timespec *ts"
.Ft void
.Fn getnanotime "struct timespec *tsp"
.Sh DESCRIPTION
The
.Fn bintime
and
.Fn getbintime
functions store the system time as a
.Vt "struct bintime"
at the addresses specified by
.Fa bt .
The
.Fn microtime
and
.Fn getmicrotime
functions perform the same utility, but record the time as a
.Vt "struct timeval"
instead.
Similarly the
.Fn nanotime
and
.Fn getnanotime
functions store the time as a
.Vt "struct timespec" .
.Pp
The
.Fn bintime ,
.Fn microtime ,
and
.Fn nanotime
functions
always query the timecounter to return the current time as precisely as
possible.
Whereas
.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 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 ,
.Xr nanouptime 9 ,
.Xr tvtohz 9
.Sh HISTORY
The
.Nm bintime
functions first appeared in
.Fx 5.0 .
The
.Nm microtime
and
.Nm nanotime
functions first appeared in
.Fx 3.0
but have existed in other incarnations since
.Bx 4.4 .
.Sh AUTHORS
This manual page was written by
.An Kelly Yancey Aq kbyanc@posi.net .
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.\" Copyright (c) 2000 Kelly Yancey`
			`.\" 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.`
			`.\"`
Fixed the misplaced $FreeBSD$. 2005-02-09 18:07:17 +00:00			`.\" $FreeBSD$`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.\"`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Dd September 16, 2004`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Dt MICROTIME 9`
mdoc(7) police: removed HISTORY info from the .Os call. 2001-07-10 15:31:11 +00:00			`.Os`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Sh NAME`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Nm bintime ,`
			`.Nm getbintime ,`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Nm microtime ,`
			`.Nm getmicrotime ,`
			`.Nm nanotime ,`
			`.Nm getnanotime`
			`.Nd get the current time`
			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In sys/time.h`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Ft void`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Fn bintime "struct bintime *bt"`
			`.Ft void`
			`.Fn getbintime "struct bintime *bt"`
			`.Ft void`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Fn microtime "struct timeval *tv"`
			`.Ft void`
			`.Fn getmicrotime "struct timeval *tv"`
			`.Ft void`
			`.Fn nanotime "struct timespec *ts"`
			`.Ft void`
			`.Fn getnanotime "struct timespec *tsp"`
			`.Sh DESCRIPTION`
			`The`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Fn bintime`
			`and`
			`.Fn getbintime`
			`functions store the system time as a`
Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00			`.Vt "struct bintime"`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`at the addresses specified by`
			`.Fa bt .`
			`The`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Fn microtime`
			`and`
			`.Fn getmicrotime`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`functions perform the same utility, but record the time as a`
Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00			`.Vt "struct timeval"`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`instead.`
			`Similarly the`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Fn nanotime`
			`and`
			`.Fn getnanotime`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`functions store the time as a`
Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00			`.Vt "struct timespec" .`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Pp`
Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00			`The`
			`.Fn bintime ,`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Fn microtime ,`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`and`
			`.Fn nanotime`
Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00			`functions`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`always query the timecounter to return the current time as precisely as`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-03 14:05:08 +00:00			`possible.`
			`Whereas`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Fn getbintime ,`
			`.Fn getmicrotime ,`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`and`
			`.Fn getnanotime`
Remove references to the (removed) kern.timecounter.method sysctl. 2000-07-23 11:12:59 +00:00			`functions are abstractions which return a less precise, but`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-03 14:05:08 +00:00			`faster to obtain, time.`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Pp`
			`The intent of the`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Fn getbintime ,`
			`.Fn getmicrotime ,`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`and`
			`.Fn getnanotime`
			`functions is to enforce the user's preference for timer accuracy versus`
			`execution time.`
			`.Sh SEE ALSO`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Xr binuptime 9 ,`
			`.Xr getbinuptime 9 ,`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Xr getmicrouptime 9 ,`
			`.Xr getnanouptime 9 ,`
			`.Xr microuptime 9 ,`
			`.Xr nanouptime 9 ,`
			`.Xr tvtohz 9`
			`.Sh HISTORY`
			`The`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Nm bintime`
			`functions first appeared in`
			`.Fx 5.0 .`
			`The`
- When bintime was added to this manpage, standalone .Nm changed from microtime to bintime. However, one standaline .Nm wasn't changed, and as a result, the manpage claimed that bintime was added in both 5.0 and 3.0. Fix by listing microtime explicitly. - Fix a grammar bogon. PR: docs/87147 (1) Submitted by: Matthew Luckie (1) MFC after: 3 days 2005-10-13 16:01:28 +00:00			`.Nm microtime`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`and`
			`.Nm nanotime`
			`functions first appeared in`
			`.Fx 3.0`
- When bintime was added to this manpage, standalone .Nm changed from microtime to bintime. However, one standaline .Nm wasn't changed, and as a result, the manpage claimed that bintime was added in both 5.0 and 3.0. Fix by listing microtime explicitly. - Fix a grammar bogon. PR: docs/87147 (1) Submitted by: Matthew Luckie (1) MFC after: 3 days 2005-10-13 16:01:28 +00:00			`but have existed in other incarnations since`
Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. 2004-09-17 07:24:18 +00:00			`.Bx 4.4 .`
Add new manpages for: microtime(9) nanotime(9) getmicrotime(9) getnanotime(9) microuptime(9) nanouptime(9) getmicrouptime(9) getnanouptime(9) tvtohz(9) Based on PR: docs/15889 Submitted by: Kelly Yancey <kbyanc@posi.net> 2000-01-07 12:42:59 +00:00			`.Sh AUTHORS`
			`This manual page was written by`
			`.An Kelly Yancey Aq kbyanc@posi.net .`