share/man/man9/microtime.9

   1 .\"     $NetBSD: microtime.9,v 1.14 2008/11/24 14:36:40 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
  94 The
  95 .Fn bintime
  96 and
  97 .Fn getbintime
  98 functions store the system time as a
  99 .Vt "struct bintime"
 100 at the addresses specified by
 101 .Fa bt .
 102 The
 103 .Fn microtime
 104 and
 105 .Fn getmicrotime
 106 functions perform the same utility, but record the time as a
 107 .Vt "struct timeval"
 108 instead.
 109 Similarly the
 110 .Fn nanotime
 111 and
 112 .Fn getnanotime
 113 functions store the time as a
 114 .Vt "struct timespec" .
 115 .Pp
 116 The
 117 .Fn bintime ,
 118 .Fn microtime ,
 119 and
 120 .Fn nanotime
 121 functions
 122 always query the timecounter to return the current time as precisely as
 123 possible.
 124 Whereas
 125 .Fn getbintime ,
 126 .Fn getmicrotime ,
 127 and
 128 .Fn getnanotime
 129 functions are abstractions which return a less precise, but
 130 faster to obtain, time.
 131 .Pp
 132 The intent of the
 133 .Fn getbintime ,
 134 .Fn getmicrotime ,
 135 and
 136 .Fn getnanotime
 137 functions is to enforce the user's preference for timer accuracy versus
 138 execution time.
 139 They should be used where a precision of
 140 .Pf 1/ Em HZ
 141 (e.g., 10 msec on a
 142 .Pf 100 Em HZ
 143 machine, see
 144 .Xr hz 9 )
 145 is acceptable or where performance is priority.
 146 .Pp
 147 The system realtime clock is guaranteed to be monotonically increasing
 148 at all times.
 149 As such, all calls to these functions are guaranteed to return a system time
 150 greater 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
 166 The implementation of the
 167 .Fn microtime
 168 family of functions is in
 169 .Pa sys/kern/kern_tc.c
 170 as a part of the
 171 .Xr timecounter 9
 172 framework.
 173 .Pp
 174 The implementation of the time counter sources used by the
 175 .Xr timecounter 9
 176 is machine dependent,
 177 hence its location in the source code tree varies from architecture to
 178 architecture.
 179 .Sh AUTHORS
 180 This manual page was written by
 181 .An Jeremy Cooper
 182 and
 183 .An Kelly Yancey Aq kbyanc@posi.net .
 184 .Sh BUGS
 185 Despite the guarantee that the system realtime clock will always be
 186 monotonically increasing,
 187 it is always possible for the system clock to be manually reset by the
 188 system administrator to any date.