lib/libc/sys/clock_gettime.2

   1 .\"     $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  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 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd July 8, 2022
  31 .Dt CLOCK_GETTIME 2
  32 .Os
  33 .Sh NAME
  34 .Nm clock_gettime ,
  35 .Nm clock_settime ,
  36 .Nm clock_getres
  37 .Nd get/set/calibrate date and time
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In time.h
  42 .Ft int
  43 .Fn clock_gettime "clockid_t clock_id" "struct timespec *tp"
  44 .Ft int
  45 .Fn clock_settime "clockid_t clock_id" "const struct timespec *tp"
  46 .Ft int
  47 .Fn clock_getres "clockid_t clock_id" "struct timespec *tp"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn clock_gettime
  51 and
  52 .Fn clock_settime
  53 system calls allow the calling process to retrieve or set the value
  54 used by a clock which is specified by
  55 .Fa clock_id .
  56 .Pp
  57 The
  58 .Fa clock_id
  59 argument can be a value obtained from
  60 .Xr clock_getcpuclockid 3
  61 or
  62 .Xr pthread_getcpuclockid 3
  63 as well as the following values:
  64 .Pp
  65 .Bl -tag -width indent -compact
  66 .It Dv CLOCK_REALTIME
  67 .It Dv CLOCK_REALTIME_PRECISE
  68 .It Dv CLOCK_REALTIME_FAST
  69 .It Dv CLOCK_REALTIME_COARSE
  70 Increments as a wall clock should.
  71 .It Dv CLOCK_MONOTONIC
  72 .It Dv CLOCK_MONOTONIC_PRECISE
  73 .It Dv CLOCK_MONOTONIC_FAST
  74 .It Dv CLOCK_MONOTONIC_COARSE
  75 Increments in SI seconds.
  76 .It Dv CLOCK_UPTIME
  77 .It Dv CLOCK_UPTIME_PRECISE
  78 .It Dv CLOCK_UPTIME_FAST
  79 .It Dv CLOCK_BOOTTIME
  80 Starts at zero when the kernel boots and increments
  81 monotonically in SI seconds while the machine is running.
  82 .It Dv CLOCK_VIRTUAL
  83 Increments only when
  84 the CPU is running in user mode on behalf of the calling process.
  85 .It Dv CLOCK_PROF
  86 Increments when the CPU is running in user or kernel mode.
  87 .It Dv CLOCK_SECOND
  88 Returns the current second without performing a full time counter
  89 query, using an in-kernel cached value of the current second.
  90 .It Dv CLOCK_PROCESS_CPUTIME_ID
  91 Returns the execution time of the calling process.
  92 .It Dv CLOCK_THREAD_CPUTIME_ID
  93 Returns the execution time of the calling thread.
  94 .El
  95 .Pp
  96 The clock IDs
  97 .Fa CLOCK_REALTIME ,
  98 .Fa CLOCK_MONOTONIC ,
  99 and
 100 .Fa CLOCK_UPTIME
 101 perform a full time counter query.
 102 The clock IDs with the _FAST suffix, i.e.,
 103 .Fa CLOCK_REALTIME_FAST ,
 104 .Fa CLOCK_MONOTONIC_FAST ,
 105 and
 106 .Fa CLOCK_UPTIME_FAST ,
 107 do not perform
 108 a full time counter query, so their accuracy is one timer tick.
 109 Similarly,
 110 .Fa CLOCK_REALTIME_PRECISE ,
 111 .Fa CLOCK_MONOTONIC_PRECISE ,
 112 and
 113 .Fa CLOCK_UPTIME_PRECISE
 114 are used to get the most exact value as possible, at the expense of
 115 execution time.
 116 The clock IDs
 117 .Fa CLOCK_REALTIME_COARSE
 118 and
 119 .Fa CLOCK_MONOTONIC_COARSE
 120 are aliases of corresponding IDs with _FAST suffix for compatibility with other
 121 systems.
 122 Finally,
 123 .Dv CLOCK_BOOTTIME
 124 is an alias for
 125 .Dv CLOCK_UPTIME
 126 for compatibility with other systems.
 127 .Pp
 128 The structure pointed to by
 129 .Fa tp
 130 is defined in
 131 .In sys/timespec.h
 132 as:
 133 .Bd -literal
 134 struct timespec {
 135         time_t  tv_sec;         /* seconds */
 136         long    tv_nsec;        /* and nanoseconds */
 137 };
 138 .Ed
 139 .Pp
 140 Only the super-user may set the time of day, using only
 141 .Fa CLOCK_REALTIME .
 142 If the system
 143 .Xr securelevel 7
 144 is greater than 1 (see
 145 .Xr init 8 ) ,
 146 the time may only be advanced.
 147 This limitation is imposed to prevent a malicious super-user
 148 from setting arbitrary time stamps on files.
 149 The system time can still be adjusted backwards using the
 150 .Xr adjtime 2
 151 system call even when the system is secure.
 152 .Pp
 153 The resolution (granularity) of a clock is returned by the
 154 .Fn clock_getres
 155 system call.
 156 This value is placed in a (non-NULL)
 157 .Fa *tp .
 158 .Sh RETURN VALUES
 159 .Rv -std
 160 .Sh ERRORS
 161 The following error codes may be set in
 162 .Va errno :
 163 .Bl -tag -width Er
 164 .It Bq Er EINVAL
 165 The
 166 .Fa clock_id
 167 or
 168 .Fa timespec
 169 argument
 170 was not a valid value.
 171 .It Bq Er EPERM
 172 A user other than the super-user attempted to set the time.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr date 1 ,
 176 .Xr adjtime 2 ,
 177 .Xr clock_getcpuclockid 3 ,
 178 .Xr ctime 3 ,
 179 .Xr pthread_getcpuclockid 3
 180 .Sh STANDARDS
 181 The
 182 .Fn clock_gettime ,
 183 .Fn clock_settime ,
 184 and
 185 .Fn clock_getres
 186 system calls conform to
 187 .St -p1003.1b-93 .
 188 The clock IDs
 189 .Fa CLOCK_REALTIME_FAST ,
 190 .Fa CLOCK_REALTIME_PRECISE ,
 191 .Fa CLOCK_MONOTONIC_FAST ,
 192 .Fa CLOCK_MONOTONIC_PRECISE ,
 193 .Fa CLOCK_UPTIME ,
 194 .Fa CLOCK_UPTIME_FAST ,
 195 .Fa CLOCK_UPTIME_PRECISE ,
 196 .Fa CLOCK_SECOND
 197 are
 198 .Fx
 199 extensions to the POSIX interface.
 200 .Sh HISTORY
 201 The
 202 .Fn clock_gettime ,
 203 .Fn clock_settime ,
 204 and
 205 .Fn clock_getres
 206 system calls first appeared in
 207 .Fx 3.0 .