18269e767SBrooks Davis.\" $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $ 28269e767SBrooks Davis.\" 38269e767SBrooks Davis.\" Copyright (c) 1980, 1991, 1993 48269e767SBrooks Davis.\" The Regents of the University of California. All rights reserved. 58269e767SBrooks Davis.\" 68269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without 78269e767SBrooks Davis.\" modification, are permitted provided that the following conditions 88269e767SBrooks Davis.\" are met: 98269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright 108269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer. 118269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright 128269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer in the 138269e767SBrooks Davis.\" documentation and/or other materials provided with the distribution. 148269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors 158269e767SBrooks Davis.\" may be used to endorse or promote products derived from this software 168269e767SBrooks Davis.\" without specific prior written permission. 178269e767SBrooks Davis.\" 188269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 198269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 208269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 218269e767SBrooks Davis.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 228269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 238269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 248269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 258269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 268269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 278269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 288269e767SBrooks Davis.\" SUCH DAMAGE. 298269e767SBrooks Davis.\" 308269e767SBrooks Davis.Dd October 27, 2023 318269e767SBrooks Davis.Dt CLOCK_GETTIME 2 328269e767SBrooks Davis.Os 338269e767SBrooks Davis.Sh NAME 348269e767SBrooks Davis.Nm clock_gettime , 358269e767SBrooks Davis.Nm clock_settime , 368269e767SBrooks Davis.Nm clock_getres 378269e767SBrooks Davis.Nd get/set/calibrate date and time 388269e767SBrooks Davis.Sh LIBRARY 398269e767SBrooks Davis.Lb libc 408269e767SBrooks Davis.Sh SYNOPSIS 418269e767SBrooks Davis.In time.h 428269e767SBrooks Davis.Ft int 438269e767SBrooks Davis.Fn clock_gettime "clockid_t clock_id" "struct timespec *tp" 448269e767SBrooks Davis.Ft int 458269e767SBrooks Davis.Fn clock_settime "clockid_t clock_id" "const struct timespec *tp" 468269e767SBrooks Davis.Ft int 478269e767SBrooks Davis.Fn clock_getres "clockid_t clock_id" "struct timespec *tp" 488269e767SBrooks Davis.Sh DESCRIPTION 498269e767SBrooks DavisThe 508269e767SBrooks Davis.Fn clock_gettime 518269e767SBrooks Davisand 528269e767SBrooks Davis.Fn clock_settime 538269e767SBrooks Davissystem calls allow the calling process to retrieve or set the value 548269e767SBrooks Davisused by a clock which is specified by 558269e767SBrooks Davis.Fa clock_id . 568269e767SBrooks Davis.Pp 578269e767SBrooks DavisThe 588269e767SBrooks Davis.Fa clock_id 598269e767SBrooks Davisargument can be a value obtained from 608269e767SBrooks Davis.Xr clock_getcpuclockid 3 618269e767SBrooks Davisor 628269e767SBrooks Davis.Xr pthread_getcpuclockid 3 638269e767SBrooks Davisas well as the following values: 648269e767SBrooks Davis.Pp 658269e767SBrooks Davis.Bl -tag -width indent -compact 668269e767SBrooks Davis.It Dv CLOCK_REALTIME 678269e767SBrooks Davis.It Dv CLOCK_REALTIME_PRECISE 688269e767SBrooks Davis.It Dv CLOCK_REALTIME_FAST 698269e767SBrooks Davis.It Dv CLOCK_REALTIME_COARSE 708269e767SBrooks DavisIncrements as a wall clock should. 718269e767SBrooks Davis.It Dv CLOCK_MONOTONIC 728269e767SBrooks Davis.It Dv CLOCK_MONOTONIC_PRECISE 738269e767SBrooks Davis.It Dv CLOCK_MONOTONIC_FAST 748269e767SBrooks Davis.It Dv CLOCK_MONOTONIC_COARSE 758269e767SBrooks DavisIncrements in SI seconds. 768269e767SBrooks Davis.It Dv CLOCK_UPTIME 778269e767SBrooks Davis.It Dv CLOCK_UPTIME_PRECISE 788269e767SBrooks Davis.It Dv CLOCK_UPTIME_FAST 798269e767SBrooks Davis.It Dv CLOCK_BOOTTIME 808269e767SBrooks DavisStarts at zero when the kernel boots and increments 818269e767SBrooks Davismonotonically in SI seconds while the machine is running. 828269e767SBrooks Davis.It Dv CLOCK_VIRTUAL 838269e767SBrooks DavisIncrements only when 848269e767SBrooks Davisthe CPU is running in user mode on behalf of the calling process. 858269e767SBrooks Davis.It Dv CLOCK_PROF 868269e767SBrooks DavisIncrements when the CPU is running in user or kernel mode. 878269e767SBrooks Davis.It Dv CLOCK_SECOND 888269e767SBrooks DavisReturns the current second without performing a full time counter 898269e767SBrooks Davisquery, using an in-kernel cached value of the current second. 908269e767SBrooks Davis.It Dv CLOCK_PROCESS_CPUTIME_ID 918269e767SBrooks DavisReturns the execution time of the calling process. 928269e767SBrooks Davis.It Dv CLOCK_THREAD_CPUTIME_ID 938269e767SBrooks DavisReturns the execution time of the calling thread. 948269e767SBrooks Davis.El 958269e767SBrooks Davis.Pp 968269e767SBrooks DavisThe clock IDs 97*2d29d2ecSEd Maste.Dv CLOCK_REALTIME , 98*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC , 998269e767SBrooks Davisand 100*2d29d2ecSEd Maste.Dv CLOCK_UPTIME 1018269e767SBrooks Davisperform a full time counter query. 1028269e767SBrooks DavisThe clock IDs with the _FAST suffix, i.e., 103*2d29d2ecSEd Maste.Dv CLOCK_REALTIME_FAST , 104*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC_FAST , 1058269e767SBrooks Davisand 106*2d29d2ecSEd Maste.Dv CLOCK_UPTIME_FAST , 1078269e767SBrooks Davisdo not perform 1088269e767SBrooks Davisa full time counter query, so their accuracy is one timer tick. 1098269e767SBrooks DavisSimilarly, 110*2d29d2ecSEd Maste.Dv CLOCK_REALTIME_PRECISE , 111*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC_PRECISE , 1128269e767SBrooks Davisand 113*2d29d2ecSEd Maste.Dv CLOCK_UPTIME_PRECISE 1148269e767SBrooks Davisare used to get the most exact value as possible, at the expense of 1158269e767SBrooks Davisexecution time. 1168269e767SBrooks DavisThe clock IDs 117*2d29d2ecSEd Maste.Dv CLOCK_REALTIME_COARSE 1188269e767SBrooks Davisand 119*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC_COARSE 1208269e767SBrooks Davisare aliases of corresponding IDs with _FAST suffix for compatibility with other 1218269e767SBrooks Davissystems. 1228269e767SBrooks DavisFinally, 123*2d29d2ecSEd Maste.Dv CLOCK_BOOTTIME 1248269e767SBrooks Davisis an alias for 125*2d29d2ecSEd Maste.Dv CLOCK_UPTIME 1268269e767SBrooks Davisfor compatibility with other systems and is unrelated to the 1278269e767SBrooks Davis.Fa kern.boottime 1288269e767SBrooks Davis.Xr sysctl 8 . 1298269e767SBrooks Davis.Pp 1308269e767SBrooks DavisThe structure pointed to by 1318269e767SBrooks Davis.Fa tp 1328269e767SBrooks Davisis defined in 1338269e767SBrooks Davis.In sys/timespec.h 1348269e767SBrooks Davisas: 1358269e767SBrooks Davis.Bd -literal 1368269e767SBrooks Davisstruct timespec { 1378269e767SBrooks Davis time_t tv_sec; /* seconds */ 1388269e767SBrooks Davis long tv_nsec; /* and nanoseconds */ 1398269e767SBrooks Davis}; 1408269e767SBrooks Davis.Ed 1418269e767SBrooks Davis.Pp 1428269e767SBrooks DavisOnly the super-user may set the time of day, using only 143*2d29d2ecSEd Maste.Dv CLOCK_REALTIME . 1448269e767SBrooks DavisIf the system 1458269e767SBrooks Davis.Xr securelevel 7 1468269e767SBrooks Davisis greater than 1 (see 1478269e767SBrooks Davis.Xr init 8 ) , 1488269e767SBrooks Davisthe time may only be advanced. 1498269e767SBrooks DavisThis limitation is imposed to prevent a malicious super-user 1508269e767SBrooks Davisfrom setting arbitrary time stamps on files. 1518269e767SBrooks DavisThe system time can still be adjusted backwards using the 1528269e767SBrooks Davis.Xr adjtime 2 1538269e767SBrooks Davissystem call even when the system is secure. 1548269e767SBrooks Davis.Pp 1558269e767SBrooks DavisThe resolution (granularity) of a clock is returned by the 1568269e767SBrooks Davis.Fn clock_getres 1578269e767SBrooks Davissystem call. 1588269e767SBrooks DavisThis value is placed in a (non-NULL) 1598269e767SBrooks Davis.Fa *tp . 1608269e767SBrooks Davis.Sh RETURN VALUES 1618269e767SBrooks Davis.Rv -std 1628269e767SBrooks Davis.Sh ERRORS 1638269e767SBrooks DavisThe following error codes may be set in 1648269e767SBrooks Davis.Va errno : 1658269e767SBrooks Davis.Bl -tag -width Er 1668269e767SBrooks Davis.It Bq Er EINVAL 1678269e767SBrooks DavisThe 1688269e767SBrooks Davis.Fa clock_id 1698269e767SBrooks Davisor 1708269e767SBrooks Davis.Fa timespec 1718269e767SBrooks Davisargument 1728269e767SBrooks Daviswas not a valid value. 1738269e767SBrooks Davis.It Bq Er EPERM 1748269e767SBrooks DavisA user other than the super-user attempted to set the time. 1758269e767SBrooks Davis.El 1768269e767SBrooks Davis.Sh SEE ALSO 1778269e767SBrooks Davis.Xr date 1 , 1788269e767SBrooks Davis.Xr adjtime 2 , 1798269e767SBrooks Davis.Xr clock_getcpuclockid 3 , 1808269e767SBrooks Davis.Xr ctime 3 , 1818269e767SBrooks Davis.Xr pthread_getcpuclockid 3 1828269e767SBrooks Davis.Sh STANDARDS 1838269e767SBrooks DavisThe 1848269e767SBrooks Davis.Fn clock_gettime , 1858269e767SBrooks Davis.Fn clock_settime , 1868269e767SBrooks Davisand 1878269e767SBrooks Davis.Fn clock_getres 1888269e767SBrooks Davissystem calls conform to 1898269e767SBrooks Davis.St -p1003.1b-93 . 1908269e767SBrooks DavisThe clock IDs 191*2d29d2ecSEd Maste.Dv CLOCK_REALTIME_FAST , 192*2d29d2ecSEd Maste.Dv CLOCK_REALTIME_PRECISE , 193*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC_FAST , 194*2d29d2ecSEd Maste.Dv CLOCK_MONOTONIC_PRECISE , 195*2d29d2ecSEd Maste.Dv CLOCK_UPTIME , 196*2d29d2ecSEd Maste.Dv CLOCK_UPTIME_FAST , 197*2d29d2ecSEd Maste.Dv CLOCK_UPTIME_PRECISE , 198*2d29d2ecSEd Maste.Dv CLOCK_SECOND 1998269e767SBrooks Davisare 2008269e767SBrooks Davis.Fx 2018269e767SBrooks Davisextensions to the POSIX interface. 2028269e767SBrooks Davis.Sh HISTORY 2038269e767SBrooks DavisThe 2048269e767SBrooks Davis.Fn clock_gettime , 2058269e767SBrooks Davis.Fn clock_settime , 2068269e767SBrooks Davisand 2078269e767SBrooks Davis.Fn clock_getres 2088269e767SBrooks Davissystem calls first appeared in 2098269e767SBrooks Davis.Fx 3.0 . 210