1.\" $NetBSD: microtime.9,v 1.15 2008/11/28 10:55:41 tsutsui Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jeremy Cooper. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" Copyright (c) 2000 Kelly Yancey 31.\" All rights reserved. 32.\" 33.\" Redistribution and use in source and binary forms, with or without 34.\" modification, are permitted provided that the following conditions 35.\" are met: 36.\" 1. Redistributions of source code must retain the above copyright 37.\" notice, this list of conditions and the following disclaimer. 38.\" 2. Redistributions in binary form must reproduce the above copyright 39.\" notice, this list of conditions and the following disclaimer in the 40.\" documentation and/or other materials provided with the distribution. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 43.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 45.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 46.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 47.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 48.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 50.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 51.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52.\" SUCH DAMAGE. 53.\" 54.\" $FreeBSD: src/share/man/man9/microtime.9,v 1.11 2005/10/13 16:01:28 jhb Exp $ 55.\" 56.Dd November 24, 2008 57.Dt MICROTIME 9 58.Os 59.Sh NAME 60.Nm bintime , 61.Nm getbintime , 62.Nm microtime , 63.Nm getmicrotime , 64.Nm nanotime , 65.Nm getnanotime 66.Nd get the current time 67.Sh SYNOPSIS 68.In sys/time.h 69.Ft void 70.Fo bintime 71.Fa "struct bintime *bt" 72.Fc 73.Ft void 74.Fo getbintime 75.Fa "struct bintime *bt" 76.Fc 77.Ft void 78.Fo "microtime" 79.Fa "struct timeval *tv" 80.Fc 81.Ft void 82.Fo getmicrotime 83.Fa "struct timeval *tv" 84.Fc 85.Ft void 86.Fo nanotime 87.Fa "struct timespec *ts" 88.Fc 89.Ft void 90.Fo getnanotime 91.Fa "struct timespec *tsp" 92.Fc 93.Sh DESCRIPTION 94The 95.Fn bintime 96and 97.Fn getbintime 98functions store the system time as a 99.Vt "struct bintime" 100at the addresses specified by 101.Fa bt . 102The 103.Fn microtime 104and 105.Fn getmicrotime 106functions perform the same utility, but record the time as a 107.Vt "struct timeval" 108instead. 109Similarly the 110.Fn nanotime 111and 112.Fn getnanotime 113functions store the time as a 114.Vt "struct timespec" . 115.Pp 116The 117.Fn bintime , 118.Fn microtime , 119and 120.Fn nanotime 121functions 122always query the timecounter to return the current time as precisely as 123possible. 124Whereas 125.Fn getbintime , 126.Fn getmicrotime , 127and 128.Fn getnanotime 129functions are abstractions which return a less precise, but 130faster to obtain, time. 131.Pp 132The intent of the 133.Fn getbintime , 134.Fn getmicrotime , 135and 136.Fn getnanotime 137functions is to enforce the user's preference for timer accuracy versus 138execution time. 139They should be used where a precision of 140.Pf 1/ Em HZ 141(e.g., 10 msec on a 142.Pf 100 Em HZ 143machine, see 144.Xr hz 9 ) 145is acceptable or where performance is priority. 146.Pp 147The system realtime clock is guaranteed to be monotonically increasing 148at all times. 149As such, all calls to these functions are guaranteed to return a system time 150greater than or equal to the system time returned in any previous calls. 151.Sh SEE ALSO 152.Xr settimeofday 2 , 153.Xr binuptime 9 , 154.Xr getbinuptime 9 , 155.Xr getmicrouptime 9 , 156.Xr getnanouptime 9 , 157.Xr hardclock 9 , 158.Xr hz 9 , 159.Xr inittodr 9 , 160.Xr microuptime 9 , 161.Xr nanouptime 9 , 162.Xr time_second 9 , 163.Xr timecounter 9 , 164.Xr tvtohz 9 165.Sh CODE REFERENCES 166The implementation of the 167.Fn microtime 168family of functions is in 169.Pa sys/kern/kern_tc.c 170as a part of the 171.Xr timecounter 9 172framework. 173.Pp 174The implementation of the time counter sources used by the 175.Xr timecounter 9 176is machine dependent, 177hence its location in the source code tree varies from architecture to 178architecture. 179.Sh AUTHORS 180This manual page was written by 181.An Jeremy Cooper 182and 183.An Kelly Yancey Aq kbyanc@posi.net . 184.Sh BUGS 185Despite the guarantee that the system realtime clock will always be 186monotonically increasing, 187it is always possible for the system clock to be manually reset by the 188system administrator to any date. 189