gen/clock_gettime.3

   1 .\"
   2 .\" Copyright (c) 1980, 1991, 1993
   3 .\" The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the University nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .Dd January 26, 2016
  30 .Dt CLOCK_GETTIME 3
  31 .Os
  32 .Sh NAME
  33 .Nm clock_gettime ,
  34 .Nm clock_settime ,
  35 .Nm clock_getres ,
  36 .Nm clock_gettime_nsec_np
  37 .Nd get/set date and time
  38 .Sh SYNOPSIS
  39 .Fd #include <time.h>
  40 .Ft int
  41 .Fn clock_gettime "clockid_t clock_id" "struct timespec *tp"
  42 .Ft int
  43 .Fn clock_settime "clockid_t clock_id" "const struct timespec *tp"
  44 .Ft int
  45 .Fn clock_getres "clockid_t clock_id" "struct timespec *tp"
  46 .Ft uint64_t
  47 .Fn clock_gettime_nsec_np "clockid_t clock_id"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn clock_gettime
  51 and
  52 .Fn clock_settime
  53 functions
  54 allow the calling process to retrieve or set the value used by a clock
  55 which is specified by
  56 .Fa clock_id .
  57 .Pp
  58 .Fa clock_id
  59 can be a value from
  60 one of 8 predefined values:
  61 .Bl -tag -width Er
  62 .It Dv CLOCK_REALTIME
  63 the system's real time (i.e. wall time) clock, expressed as the amount of time
  64 since the Epoch.
  65 This is the same as the value returned by
  66 .Xr gettimeofday 2 .
  67 .It Dv CLOCK_MONOTONIC
  68 clock that increments monotonically, tracking the time since an arbitrary
  69 point, and will continue to increment while the system is asleep.
  70 .It Dv CLOCK_MONOTONIC_RAW
  71 clock that increments monotonically, tracking the time since an arbitrary point
  72 like CLOCK_MONOTONIC.  However, this clock is unaffected by frequency or time
  73 adjustments.  It should not be compared to other system time sources.
  74 .It Dv CLOCK_MONOTONIC_RAW_APPROX
  75 like CLOCK_MONOTONIC_RAW, but reads a value cached by the system at context
  76 switch.  This can be read faster, but at a loss of accuracy as it may return
  77 values that are milliseconds old.
  78 .It Dv CLOCK_UPTIME_RAW
  79 clock that increments monotonically, in the same manner as
  80 .Dv CLOCK_MONOTONIC_RAW,
  81 but that does not increment while the system is asleep.
  82 The returned value is identical to the result of
  83 .Fn mach_absolute_time
  84 after the appropriate mach_timebase conversion is applied.
  85 .It Dv CLOCK_UPTIME_RAW_APPROX
  86 like CLOCK_UPTIME_RAW, but reads a value cached by the system at context
  87 switch.  This can be read faster, but at a loss of accuracy as it may return
  88 values that are milliseconds old.
  89 .It Dv CLOCK_PROCESS_CPUTIME_ID
  90 clock that tracks the amount of CPU (in user- or kernel-mode) used by the
  91 calling process.
  92 .It Dv CLOCK_THREAD_CPUTIME_ID
  93 clock that tracks the amount of CPU (in user- or kernel-mode) used by the
  94 calling thread.
  95 .El
  96 .Pp
  97 The structure pointed to by
  98 .Fa tp
  99 is defined in
 100 .In sys/time.h
 101 as:
 102 .Bd -literal -offset indent
 103 struct timespec {
 104     time_t  tv_sec;     /* seconds */
 105     long    tv_nsec;    /* and nanoseconds */
 106 };
 107 .Ed
 108 .Pp
 109 Only the
 110 .Dv CLOCK_REALTIME
 111 clock can be set, and only the superuser may do so.
 112 .Pp
 113 The resolution of a clock is returned by the
 114 .Fn clock_getres
 115 call.
 116 This value is placed in a (non-null)
 117 .Fa *tp .
 118 This value may be smaller than the actual precision of the underlying clock,
 119 but represents a lower bound on the resolution.
 120 .Pp
 121 As a non-portable extension, the
 122 .Fn clock_gettime_nsec_np
 123 function will return the clock value in 64-bit nanoseconds.
 124 .Sh RETURN VALUES
 125 A 0 return value indicates that the call succeeded.
 126 A \-1 return value indicates an error occurred, and in this
 127 case an error code is stored into the global variable
 128 .Va errno .
 129 For
 130 .Fn clock_gettime_nsec_np
 131 a return value of non-0 indicates success.  A 0 return value indicates an error
 132 occurred and an error code is stored in
 133 .Va errno .
 134 .Sh ERRORS
 135 .Fn clock_gettime ,
 136 .Fn clock_settime ,
 137 .Fn clock_getres ,
 138 and
 139 .Fn clock_gettime_nsec_np
 140 will fail if:
 141 .Bl -tag -width Er
 142 .It Bq Er EINVAL
 143 .Fa clock_id
 144 is not a valid value.
 145 .It Bq Er EFAULT
 146 The
 147 .Fa tp
 148 argument address referenced invalid memory.
 149 .El
 150 .Pp
 151 In addition,
 152 .Fn clock_settime
 153 may return the following errors:
 154 .Bl -tag -width Er
 155 .It Bq Er EPERM
 156 A user other than the superuser attempted to set the time.
 157 .It Bq Er EINVAL
 158 .Fa clock_id
 159 specifies a clock that isn't settable,
 160 .Fa tp
 161 specifies a nanosecond value less than zero or greater than 1000 million,
 162 or a value outside the range of the specified clock.
 163 .El
 164 .Sh SEE ALSO
 165 .Xr date 1 ,
 166 .Xr getitimer 2 ,
 167 .Xr gettimeofday 2 ,
 168 .Sh HISTORY
 169 These functions first appeared
 170 in
 171 Mac OSX 10.12
 172 .Sh STANDARDS
 173 The
 174 .Fn clock_gettime ,
 175 .Fn clock_settime ,
 176 and
 177 .Fn clock_getres
 178 system calls conform to
 179 .St -p1003.1b-93 .
 180 .Fn cleck_gettime_nsec_np
 181 is a non-portable Darwin extension.
 182 The clock IDs
 183 .Fa CLOCK_MONOTONIC_RAW
 184 and
 185 .Fa CLOCK_UPTIME_RAW
 186 are extensions to the POSIX interface.