1.\" $OpenBSD: microtime.9,v 1.23 2022/12/28 15:46:39 cheloha Exp $ 2.\" $NetBSD: microtime.9,v 1.2 1999/03/16 00:40:47 garbled Exp $ 3.\" 4.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jeremy Cooper. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: December 28 2022 $ 32.Dt MICROTIME 9 33.Os 34.Sh NAME 35.Nm microuptime , 36.Nm getmicrouptime , 37.Nm nanouptime , 38.Nm getnanouptime , 39.Nm nsecuptime , 40.Nm getnsecuptime , 41.Nm getuptime , 42.Nm nanoruntime , 43.Nm getnsecruntime , 44.Nm microtime , 45.Nm getmicrotime , 46.Nm nanotime , 47.Nm getnanotime , 48.Nm gettime , 49.Nm microboottime , 50.Nm nanoboottime 51.Nd get the time 52.Sh SYNOPSIS 53.In sys/time.h 54.Ft void 55.Fo microuptime 56.Fa "struct timeval *tv" 57.Fc 58.Ft void 59.Fo getmicrouptime 60.Fa "struct timeval *tv" 61.Fc 62.Ft void 63.Fo nanouptime 64.Fa "struct timespec *ts" 65.Fc 66.Ft void 67.Fo getnanouptime 68.Fa "struct timespec *ts" 69.Fc 70.Ft uint64_t 71.Fo nsecuptime 72.Fa "void" 73.Fc 74.Ft uint64_t 75.Fo getnsecuptime 76.Fa "void" 77.Fc 78.Ft time_t 79.Fo getuptime 80.Fa "void" 81.Fc 82.Ft void 83.Fo nanoruntime 84.Fa "struct timespec *ts" 85.Fc 86.Ft uint64_t 87.Fo getnsecruntime 88.Fa "void" 89.Fc 90.Ft void 91.Fo microtime 92.Fa "struct timeval *tv" 93.Fc 94.Ft void 95.Fo getmicrotime 96.Fa "struct timeval *tv" 97.Fc 98.Ft void 99.Fo nanotime 100.Fa "struct timespec *ts" 101.Fc 102.Ft void 103.Fo getnanotime 104.Fa "struct timespec *ts" 105.Fc 106.Ft time_t 107.Fo gettime 108.Fa "void" 109.Fc 110.Ft void 111.Fo microboottime 112.Fa "struct timeval *tv" 113.Fc 114.Ft void 115.Fo nanoboottime 116.Fa "struct timespec *ts" 117.Fc 118.Sh DESCRIPTION 119The kernel has three clocks and a variety of interfaces for reading them. 120.Pp 121The 122.Sy uptime 123clock measures the time elapsed since the system booted. 124It begins at zero and advances monotonically. 125The uptime clock may be read with the following functions: 126.Bl -column "getmicrouptimeX" "Output Format" "Source" -offset indent 127.It Em Name Ta Em Output Format Ta Em Source 128.It Fn microuptime Ta Vt struct timeval Ta hardware 129.It Fn getmicrouptime Ta Vt struct timeval Ta timestamp 130.It Fn nanouptime Ta Vt struct timespec Ta hardware 131.It Fn getnanouptime Ta Vt struct timespec Ta timestamp 132.It Fn nsecuptime Ta Ft uint64_t Ta hardware 133.It Fn getnsecuptime Ta Ft uint64_t Ta timestamp 134.It Fn getuptime Ta Ft time_t Ta timestamp 135.El 136.Pp 137The 138.Sy runtime 139clock measures the time elapsed since the system booted, 140less any time the system is suspended or hibernating. 141It begins at zero and normally advances monotonically, 142but pauses while the system is suspended or hibernating. 143The runtime clock may be read with the following functions: 144.Bl -column "getnsecruntimeX" "Output Format" "Source" -offset indent 145.It Em Name Ta Em Output Format Ta Em Source 146.It Fn nanoruntime Ta Vt struct timespec Ta hardware 147.It Fn getnsecruntime Ta Ft uint64_t Ta timestamp 148.El 149.Pp 150The 151.Sy UTC 152clock measures the time elapsed since Jan 1 1970 00:00:00 153.Pq the Unix Epoch . 154The clock normally advances monotonically, 155but jumps when a process calls 156.Xr clock_settime 2 157or 158.Xr settimeofday 2 . 159The UTC clock may be read with the following functions: 160.Bl -column "getmicrotimeX" "Output Format" "Source" -offset indent 161.It Em Name Ta Em Output Format Ta Em Source 162.It Fn microtime Ta Vt struct timeval Ta hardware 163.It Fn getmicrotime Ta Vt struct timeval Ta timestamp 164.It Fn nanotime Ta Vt struct timespec Ta hardware 165.It Fn getnanotime Ta Vt struct timespec Ta timestamp 166.It Fn gettime Ta Ft time_t Ta timestamp 167.El 168.Pp 169The kernel also maintains a 170.Sy boot timestamp . 171It is the moment on the UTC clock when the system booted. 172The timestamp jumps when a process calls 173.Xr clock_settime 2 174or 175.Xr settimeofday 2 . 176The boot timestamp may be read with the following functions: 177.Bl -column "microboottimeX" "Output Format" "Source" -offset indent 178.It Em Name Ta Em Output Format Ta Em Source 179.It Fn microboottime Ta Vt struct timeval Ta timestamp 180.It Fn nanoboottime Ta Vt struct timespec Ta timestamp 181.El 182.Pp 183Functions that source from the 184.Em hardware 185provide the most precise result possible. 186Functions that source from a 187.Em timestamp 188provide a far less precise result, 189but do so very quickly. 190On most platforms, 191timestamps are updated approximately 100 times per second. 192.Sh CONTEXT 193These functions may be called during autoconf, 194from process context, 195or from any interrupt context. 196.Sh RETURN VALUES 197.Fn nsecuptime , 198.Fn getnsecuptime , 199and 200.Fn getnsecruntime 201return a count of nanoseconds. 202.Pp 203.Fn getuptime 204and 205.Fn gettime 206return a count of seconds. 207.Sh ERRORS 208These functions are always successful, 209and no return value is reserved to indicate an error. 210.Sh CODE REFERENCES 211.Pa sys/kern/kern_tc.c 212.Sh SEE ALSO 213.Xr clock_settime 2 , 214.Xr settimeofday 2 , 215.Xr timeradd 3 , 216.Xr hardclock 9 , 217.Xr hz 9 , 218.Xr inittodr 9 , 219.Xr tc_init 9 220