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 5 .
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 5   .
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 5 .
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 5
288