1.\" $OpenBSD: clock_gettime.2,v 1.31 2020/10/25 00:54:51 cheloha 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 $Mdocdate: October 25 2020 $ 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 or set the time 38.Sh SYNOPSIS 39.In time.h 40.Ft int 41.Fn clock_gettime "clockid_t clock" "struct timespec *now" 42.Ft int 43.Fn clock_settime "clockid_t clock" "const struct timespec *now" 44.Ft int 45.Fn clock_getres "clockid_t clock" "struct timespec *res" 46.Sh DESCRIPTION 47The 48.Fn clock_gettime 49function reads the given 50.Fa clock 51and writes its absolute value to 52.Fa now . 53The 54.Fa clock 55may be a value returned by 56.Xr clock_getcpuclockid 3 57or 58.Xr pthread_getcpuclockid 3 , 59or any of the following constants: 60.Bl -tag -width CLOCK_MONOTONIC 61.It Dv CLOCK_REALTIME 62The Coordinated Universal Time 63.Pq UTC 64clock. 65Its absolute value is the time elapsed since 66Jan 1 1970 00:00:00 UTC 67.Pq the Epoch . 68The clock normally advances continuously, 69though it may jump discontinuously if a process calls 70.Xr settimeofday 2 71or 72.Fn clock_settime 73.Pq see below . 74.It Dv CLOCK_MONOTONIC 75The monotonic clock. 76Its absolute value is meaningless. 77The clock begins at an undefined positive point and advances continuously. 78.It Dv CLOCK_BOOTTIME 79The uptime clock. 80Its absolute value is the time elapsed since the system booted. 81The clock begins at zero and advances continuously. 82.It Dv CLOCK_UPTIME 83The runtime clock. 84Its absolute value is the time elapsed since the system booted 85less any time the system was suspended. 86The clock begins at zero and advances while the system is not suspended. 87.It Dv CLOCK_PROCESS_CPUTIME_ID 88The process CPU clock. 89Its absolute value begins at zero and advances while the calling process 90is running in user or kernel mode. 91.It Dv CLOCK_THREAD_CPUTIME_ID 92The thread CPU clock. 93Its absolute value begins at zero and advances while the calling thread 94is running in user or kernel mode. 95.El 96.Pp 97The 98.Fn clock_settime 99function sets the given 100.Fa clock 101to the absolute value 102.Fa now . 103Only the 104.Dv CLOCK_REALTIME 105clock may be set and only the superuser may set it. 106If the system 107.Xr securelevel 7 108is 2 or greater the time may only be advanced. 109This limitation is imposed to prevent a malicious superuser 110from setting arbitrary timestamps on files. 111.Pp 112The 113.Fn clock_getres 114function retrieves the resolution of the given 115.Fa clock 116and writes it to 117.Fa res 118if 119.Fa res 120is 121.Pf non- Dv NULL . 122The 123.Fa clock 124may be any of the clocks accepted by 125.Fn clock_gettime 126as described earlier. 127.Pp 128The 129.Fa now 130and 131.Fa res 132arguments are 133.Dv timespec 134structures as defined in 135.In sys/time.h : 136.Bd -literal -offset indent 137struct timespec { 138 time_t tv_sec; /* seconds */ 139 long tv_nsec; /* and nanoseconds */ 140}; 141.Ed 142.Sh RETURN VALUES 143.Rv -std 144.Sh EXAMPLES 145Use the 146.Dv CLOCK_REALTIME 147clock to determine the time of day. 148Its absolute value can be passed to functions like 149.Xr gmtime 3 150and 151.Xr strftime 3 152to produce a human-readable string: 153.Bd -literal -offset indent 154char str[64]; 155struct timespec now; 156struct tm *tmbuf; 157 158clock_gettime(CLOCK_REALTIME, &now); 159tmbuf = gmtime(&now.tv_sec); 160if (tmbuf == NULL) 161 err(1, "gmtime"); 162if (strftime(str, sizeof(str), "%a %b %e %T %Y %Z", tmbuf) == 0) 163 err(1, "strftime"); 164printf("%s (%lld.%09ld seconds since the Epoch)\\n", 165 str, (long long)now.tv_sec, now.tv_nsec); 166.Ed 167.Pp 168Use the 169.Dv CLOCK_MONOTONIC 170clock to measure elapsed time. 171The 172.Xr timespecsub 3 173function simplifies arithmetic operations on 174.Dv timespec 175structures: 176.Bd -literal -offset indent 177struct timespec elapsed, start, stop, timeout; 178 179timeout.tv_sec = 2; 180timeout.tv_nsec = 500000000; 181 182clock_gettime(CLOCK_MONOTONIC, &start); 183nanosleep(&timeout, NULL); 184clock_gettime(CLOCK_MONOTONIC, &stop); 185 186timespecsub(&stop, &start, &elapsed); 187printf("nanosleep: expected %lld.%09ld actual %lld.%09ld\\n", 188 (long long)timeout.tv_sec, timeout.tv_nsec, 189 (long long)elapsed.tv_sec, elapsed.tv_nsec); 190.Ed 191.Pp 192Use the 193.Dv CLOCK_PROCESS_CPUTIME_ID 194or 195.Dv CLOCK_THREAD_CPUTIME_ID 196clocks to measure CPU time instead of elapsed time: 197.Bd -literal -offset indent 198struct timespec cputime, start, stop; 199volatile int i; 200 201clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start); 202for (i = 0; i < INT_MAX; i++) 203 continue; 204clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &stop); 205 206timespecsub(&stop, &start, &cputime); 207printf("CPU time: %lld.%09lds\\n", 208 (long long)cputime.tv_sec, cputime.tv_nsec); 209.Ed 210.Pp 211How much time has elapsed since the system booted? 212Has the system been suspended for any of that time? 213.Bd -literal -offset indent 214struct timespec diff, total, running; 215 216clock_gettime(CLOCK_BOOTTIME, &total); 217clock_gettime(CLOCK_UPTIME, &running); 218timespecsub(&total, &running, &diff); 219 220printf("Seconds since boot: %8lld.%09ld\\n", 221 (long long)total.tv_sec, total.tv_nsec); 222printf("Seconds suspended: %8lld.%09ld\\n", 223 (long long)diff.tv_sec, diff.tv_nsec); 224.Ed 225.Pp 226Set the 227.Dv CLOCK_REALTIME 228clock to Jan 1 00:00:00 2000 UTC: 229.Bd -literal -offset indent 230struct tm y2k; 231struct timespec ts; 232 233y2k.tm_year = 100; /* 2000 */ 234y2k.tm_mon = 0; /* January */ 235y2k.tm_mday = 1; 236y2k.tm_hour = 0; 237y2k.tm_min = 0; 238y2k.tm_sec = 0; 239 240ts.tv_nsec = 0; 241ts.tv_sec = timegm(&y2k); 242if (ts.tv_sec == -1) 243 err(1, "timegm"); 244 245if (clock_settime(CLOCK_REALTIME, &ts) == -1) 246 err(1, "clock_settime"); 247.Ed 248.Sh ERRORS 249.Fn clock_gettime , 250.Fn clock_settime , 251and 252.Fn clock_getres 253will fail if: 254.Bl -tag -width Er 255.It Bq Er EINVAL 256The 257.Fa clock 258is invalid. 259.It Bq Er EFAULT 260.Fa now 261or 262.Fa res 263reference invalid memory. 264.El 265.Pp 266In addition, 267.Fn clock_settime 268may return the following errors: 269.Bl -tag -width Er 270.It Bq Er EPERM 271A user other than the superuser attempted to set the time. 272.It Bq Er EINVAL 273The 274.Fa clock 275is not 276.Dv CLOCK_REALTIME . 277.It Bq Er EINVAL 278.Fa now 279specifies a nanosecond value less than zero or greater than or equal to 280one billion. 281.It Bq Er EINVAL 282.Fa now 283specifies a value outside the range of the given 284.Fa clock . 285.El 286.Sh SEE ALSO 287.Xr date 1 , 288.Xr adjtime 2 , 289.Xr getitimer 2 , 290.Xr gettimeofday 2 , 291.Xr clock_getcpuclockid 3 , 292.Xr ctime 3 , 293.Xr pthread_getcpuclockid 3 , 294.Xr strftime 3 , 295.Xr time 3 , 296.Xr timespecadd 3 , 297.Xr securelevel 7 298.Sh STANDARDS 299The 300.Fn clock_gettime , 301.Fn clock_settime , 302and 303.Fn clock_getres 304functions conform to 305.St -p1003.1-2008 . 306.Pp 307The 308.Dv CLOCK_BOOTTIME 309and 310.Dv CLOCK_UPTIME 311clocks are extensions to that specification. 312.Sh HISTORY 313The 314.Fn clock_gettime , 315.Fn clock_settime , 316and 317.Fn clock_getres 318functions and the 319.Dv CLOCK_REALTIME 320clock first appeared in 321.St -p1003.1b-93 322and were first available in 323.Ox 2.1 . 324.Pp 325The 326.Dv CLOCK_MONOTONIC 327clock first appeared in 328IEEE Std 1003.1j-2000 329.Pq Qo POSIX.1j Qc 330and was first available in 331.Ox 3.4 . 332.Pp 333The 334.Dv CLOCK_PROCESS_CPUTIME_ID 335and 336.Dv CLOCK_THREAD_CPUTIME_ID 337clocks first appeared in 338IEEE Std 1003.1d-1999 339.Pq Qo POSIX.1d Qc 340and were first available in 341.Ox 5.4 . 342.Pp 343The 344.Dv CLOCK_UPTIME 345clock first appeared in 346.Fx 7.0 347and was first available in 348.Ox 5.5 . 349.Pp 350The 351.Dv CLOCK_BOOTTIME 352clock first appeared in 353Linux 2.6.39 354and was first available in 355.Ox 6.3 . 356