share/man/man9/microuptime.9

   1 .\" $NetBSD: microuptime.9,v 1.7 2008/11/26 18:40:22 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2000 Kelly Yancey
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man9/microuptime.9,v 1.7 2005/01/12 21:48:25 ru Exp $
  28 .\"
  29 .Dd November 24, 2008
  30 .Dt MICROUPTIME 9
  31 .Os
  32 .Sh NAME
  33 .Nm binuptime ,
  34 .Nm getbinuptime ,
  35 .Nm microuptime ,
  36 .Nm getmicrouptime ,
  37 .Nm nanouptime ,
  38 .Nm getnanouptime
  39 .Nd get the time elapsed since boot
  40 .Sh SYNOPSIS
  41 .In sys/time.h
  42 .Ft void
  43 .Fn binuptime "struct bintime *bt"
  44 .Ft void
  45 .Fn getbinuptime "struct bintime *bt"
  46 .Ft void
  47 .Fn microuptime "struct timeval *tv"
  48 .Ft void
  49 .Fn getmicrouptime "struct timeval *tv"
  50 .Ft void
  51 .Fn nanouptime "struct timespec *ts"
  52 .Ft void
  53 .Fn getnanouptime "struct timespec *tsp"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn binuptime
  57 and
  58 .Fn getbinuptime
  59 functions store the time elapsed since boot as a
  60 .Vt "struct bintime"
  61 at the address specified by
  62 .Fa bt .
  63 The
  64 .Fn microuptime
  65 and
  66 .Fn getmicrouptime
  67 functions perform the same utility, but record the elapsed time as a
  68 .Vt "struct timeval"
  69 instead.
  70 Similarly the
  71 .Fn nanouptime
  72 and
  73 .Fn getnanouptime
  74 functions store the elapsed time as a
  75 .Vt "struct timespec" .
  76 .Pp
  77 The
  78 .Fn binuptime ,
  79 .Fn microuptime ,
  80 and
  81 .Fn nanouptime
  82 functions
  83 always query the timecounter to return the current time as precisely as
  84 possible.
  85 Whereas
  86 .Fn getbinuptime ,
  87 .Fn getmicrouptime ,
  88 and
  89 .Fn getnanouptime
  90 functions are abstractions which return a less precise, but
  91 faster to obtain, time.
  92 .Pp
  93 The intent of the
  94 .Fn getbinuptime ,
  95 .Fn getmicrouptime ,
  96 and
  97 .Fn getnanouptime
  98 functions is to enforce the user's preference for timer accuracy versus
  99 execution time.
 100 They should be used where a precision of
 101 .Pf 1/ Em HZ
 102 (e.g., 10 msec on a
 103 .Pf 100 Em HZ
 104 machine, see
 105 .Xr hz 9 )
 106 is acceptable or where performance is priority.
 107 .Sh SEE ALSO
 108 .Xr bintime 9 ,
 109 .Xr getbintime 9 ,
 110 .Xr getmicrotime 9 ,
 111 .Xr getnanotime 9 ,
 112 .Xr hz 9 ,
 113 .Xr microtime 9 ,
 114 .Xr nanotime 9 ,
 115 .Xr timecounter 9 ,
 116 .Xr tvtohz 9
 117 .Sh AUTHORS
 118 This manual page was written by
 119 .An Kelly Yancey Aq kbyanc@posi.net .