1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright 1989 AT&T 44.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved 45.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 46.\" Copyright 2021 Oxide Computer Company 47.\" 48.Dd October 3, 2021 49.Dt CLOCK_SETTIME 3C 50.Os 51.Sh NAME 52.Nm clock_settime , 53.Nm clock_gettime , 54.Nm clock_getres 55.Nd high-resolution clock operations 56.Sh SYNOPSIS 57.In time.h 58.Ft int 59.Fo clock_settime 60.Fa "clockid_t clock_id" 61.Fa "const struct timespec *tp" 62.Fc 63.Ft int 64.Fo clock_gettime 65.Fa "clockid_t clock_id" 66.Fa "struct timespec *tp" 67.Fc 68.Ft int 69.Fo clock_getres 70.Fa "clockid_t clock_id" 71.Fa "struct timespec *res" 72.Fc 73.Sh DESCRIPTION 74The 75.Fn clock_settime 76function sets the specified clock, 77.Fa clock_id , 78to the value specified by 79.Fa tp . 80Time values that are between two consecutive non-negative integer multiples of 81the resolution of the specified clock are truncated down to the smaller multiple 82of the resolution. 83.Pp 84The 85.Fn clock_gettime 86function returns the current value 87.Fa tp 88for the specified clock, 89.Fa clock_id . 90.Pp 91The resolution of any clock can be obtained by calling 92.Fn clock_getres 93Clock resolutions are system-dependent and cannot be set by a process. 94If the argument 95.Fa res 96is not 97.Dv NULL , 98the resolution of the specified clock is stored in the location pointed to by 99.Fa res . 100If 101.Fa res 102is 103.Dv NULL , 104the clock resolution is not returned. 105If the time argument of 106.Fn clock_settime 107is not a multiple of 108.Fa res , 109then the value is truncated to a multiple of 110.Fa res . 111.Pp 112A clock may be system wide 113.Pq that is, visible to all processes 114or per-process 115.Pq measuring time that is meaningful only within a process . 116.Pp 117The following clocks are supported in the system and defined by 118including 119.In time.h : 120.Bl -tag -width Ds 121.It Dv CLOCK_REALTIME 122This clock represents the realtime clock for the system. 123For this clock, the values returned by 124.Fn clock_gettime 125and specified by 126.Fn clock_settime 127represent the amount of time 128.Pq in seconds and nanoseconds 129since the Epoch. 130.It Dv CLOCK_HIGHRES 131This clock represents the non-adjustable, high-resolution clock for the system. 132For this clock, the value returned by 133.Fn clock_gettime 134represents the amount of time (in seconds and nanoseconds) since some arbitrary 135time in the past; it is not correlated in any way to the time of day, and thus 136is not subject to resetting or drifting by way of 137.Xr adjtime 2 , 138.Xr ntp adjtime 2 , 139.Xr settimeofday 3C , 140or 141.Fn clock_settime . 142The time source for this clock is the same as that for 143.Xr gethrtime 3C . 144.Pp 145It is not possible to set this clock with 146.Fn clock_settime . 147.Pp 148.Dv CLOCK_MONOTONIC 149is an alias for this clock. 150Other systems define a 151.Dv CLOCK_MONOTONIC_RAW 152for a high-resolution clock which is not subject to adjustments. 153.Dv CLOCK_HIGHRES 154is not subject to time of day adjustments and thus can always be safely 155used here. 156.It Dv CLOCK_VIRTUAL 157This clock represents the amount of CPU-time 158.Pq in seconds and nanoseconds 159that the calling thread has spent executing user code. 160This is the same as the 161.Fa pr_utime 162member of the 163.Vt prusage_t 164and 165.Fa pr_utime 166member of the 167.Vt lwpsinfo_t 168structure discussed in 169.Xr proc 4 . 170.Pp 171This clock cannot be set with 172.Fn clock_settime 173and has the same source as 174.Xr gethrvtime 3C . 175.It Dv CLOCK_THREAD_CPUTIME_ID 176This clock is similar to 177.Dv CLOCK_VIRTUAL ; 178however, it also includes the system time of the calling thread in 179addition to the user time. 180.Pp 181The system time is the same that is seen in the 182.Fa pr_stime 183member of the 184.Vt lwpsinfo_t 185structure discussed in 186.Xr proc 4 . 187System time includes both the system and trap microstates, 188.Fa pr_stime 189and 190.Fa pr_ttime 191of the 192.Vt prusage_t 193structure respectively. 194.Pp 195This clock cannot be set with 196.Fn clock_settime 197and it has an alias of 198.Dv CLOCK_PROF . 199.It Dv ClOCK_PROCESS_CPUTIME_ID 200This clock represents the total CPU-time that the process 201.Pq but not children 202has spent in both user and system time for the calling process. 203This is equivalent to the combination of the 204.Fa pr_utime 205and 206.Fa pr_stime 207members of the 208.Vt psinfo_t 209structure documented in 210.Xr proc 4 . 211.Pp 212This clock is not settable with 213.Fn clock_settime . 214.El 215.Sh RETURN VALUES 216Upon successful completion, 217.Sy 0 218is returned. 219Otherwise, 220.Sy -1 221is returned and 222.Va errno 223is set to indicate the error. 224.Sh ERRORS 225The 226.Fn clock_settime , 227.Fn clock_gettime , 228and 229.Fn clock_getres 230functions will fail if: 231.Bl -tag -width Er 232.It Er EINVAL 233The 234.Fa clock_id 235argument does not specify a known clock. 236.It Er ENOSYS 237The functions 238.Fn \fBclock_settime , 239.Fn \fBclock_gettime , 240and 241.Fn clock_getres 242are not supported by this implementation. 243Note, this error should not occur here. 244.El 245.Pp 246The 247.Fn clock_settime 248function will fail if: 249.Bl -tag -width Er 250.It Er EINVAL 251The 252.Fa tp 253argument is outside the range for the given clock ID; or the 254.Fa tp 255argument specified a nanosecond value less than zero or greater than or 256equal to 1000 million. 257.Pp 258The clock specified by 259.Fa clock_id 260does not support being set. 261.El 262.Pp 263The 264.Fn clock_settime 265function may fail if: 266.Bl -tag -width Er 267.It Er EPERM 268The requesting process does not have the appropriate privilege to set the 269specified clock. 270.El 271.Sh INTERFACE STABILITY 272.Sy Committed 273.Sh MT-LEVEL 274.Fn clock_gettime 275is 276.Sy Async-Signal-Safe 277.Sh SEE ALSO 278.Xr adjtime 2 , 279.Xr ntp_adjtime 2 , 280.Xr time 2 , 281.Xr ctime 3C , 282.Xr gethrtime 3C , 283.Xr gethrvtime 3C , 284.Xr settimeofday 3C , 285.Xr timer_gettime 3C , 286.Xr time.h 3HEAD , 287.Xr proc 4 288