1.\" $NetBSD: microtime.9,v 1.18 2010/06/08 05:50:01 jruoho 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 June 8, 2010 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" . 115The structures are described in 116.Xr timeval 3 . 117.Pp 118The 119.Fn bintime , 120.Fn microtime , 121and 122.Fn nanotime 123functions 124always query the timecounter to return the current time as precisely as 125possible. 126Whereas 127.Fn getbintime , 128.Fn getmicrotime , 129and 130.Fn getnanotime 131functions are abstractions which return a less precise, but 132faster to obtain, time. 133.Pp 134The intent of the 135.Fn getbintime , 136.Fn getmicrotime , 137and 138.Fn getnanotime 139functions is to enforce the user's preference for timer accuracy versus 140execution time. 141They should be used where a precision of 142.Pf 1/ Em HZ 143(e.g., 10 msec on a 144.Pf 100 Em HZ 145machine, see 146.Xr hz 9 ) 147is acceptable or where performance is priority. 148.Pp 149The system realtime clock is guaranteed to be monotonically increasing 150at all times. 151As such, all calls to these functions are guaranteed to return a system time 152greater than or equal to the system time returned in any previous calls. 153Comparable functions exist to retrieve the time elapsed since boot; see 154.Xr microuptime 9 . 155.Sh SEE ALSO 156.Xr settimeofday 2 , 157.Xr bintime_add 9 , 158.Xr inittodr 9 , 159.Xr time_second 9 , 160.Xr tvtohz 9 161.Sh CODE REFERENCES 162The implementation of the 163.Fn microtime 164family of functions is in 165.Pa sys/kern/kern_tc.c 166as a part of the 167.Xr timecounter 9 168framework. 169.Pp 170The implementation of the time counter sources used by the 171.Xr timecounter 9 172is machine dependent, 173hence its location in the source code tree varies from architecture to 174architecture. 175.Sh AUTHORS 176This manual page was written by 177.An Jeremy Cooper 178and 179.An Kelly Yancey Aq kbyanc@posi.net . 180.Sh BUGS 181Despite the guarantee that the system realtime clock will always be 182monotonically increasing, 183it is always possible for the system clock to be manually reset by the 184system administrator to any date. 185