xref: /illumos-gate/usr/src/man/man3c/clock_settime.3c (revision bbf215553c7233fbab8a0afdf1fac74c44781867)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd October 3, 2021
.Dt CLOCK_SETTIME 3C
.Os
.Sh NAME
.Nm clock_settime ,
.Nm clock_gettime ,
.Nm clock_getres
.Nd high-resolution clock operations
.Sh SYNOPSIS
.In time.h
.Ft int
.Fo clock_settime
.Fa "clockid_t clock_id"
.Fa "const struct timespec *tp"
.Fc
.Ft int
.Fo clock_gettime
.Fa "clockid_t clock_id"
.Fa "struct timespec *tp"
.Fc
.Ft int
.Fo clock_getres
.Fa "clockid_t clock_id"
.Fa "struct timespec *res"
.Fc
.Sh DESCRIPTION
The
.Fn clock_settime
function sets the specified clock,
.Fa clock_id ,
to the value specified by
.Fa tp .
Time values that are between two consecutive non-negative integer multiples of
the resolution of the specified clock are truncated down to the smaller multiple
of the resolution.
.Pp
The
.Fn clock_gettime
function returns the current value
.Fa tp
for the specified clock,
.Fa clock_id .
.Pp
The resolution of any clock can be obtained by calling
.Fn clock_getres
Clock resolutions are system-dependent and cannot be set by a process.
If the argument
.Fa res
is not
.Dv NULL ,
the resolution of the specified clock is stored in the location pointed to by
.Fa res .
If
.Fa res
is
.Dv NULL ,
the clock resolution is not returned.
If the time argument of
.Fn clock_settime
is not a multiple of
.Fa res ,
then the value is truncated to a multiple of
.Fa res .
.Pp
A clock may be system wide
.Pq that is, visible to all processes
or per-process
.Pq measuring time that is meaningful only within a process .
.Pp
The following clocks are supported in the system and defined by
including
.In time.h :
.Bl -tag -width Ds
.It Dv CLOCK_REALTIME
This clock represents the realtime clock for the system.
For this clock, the values returned by
.Fn clock_gettime
and specified by
.Fn clock_settime
represent the amount of time
.Pq in seconds and nanoseconds
since the Epoch.
.It Dv CLOCK_HIGHRES
This clock represents the non-adjustable, high-resolution clock for the system.
For this clock, the value returned by
.Fn clock_gettime
represents the amount of time (in seconds and nanoseconds) since some arbitrary
time in the past; it is not correlated in any way to the time of day, and thus
is not subject to resetting or drifting by way of
.Xr adjtime 2 ,
.Xr ntp_adjtime 2 ,
.Xr settimeofday 3C ,
or
.Fn clock_settime .
The time source for this clock is the same as that for
.Xr gethrtime 3C .
.Pp
It is not possible to set this clock with
.Fn clock_settime .
.Pp
.Dv CLOCK_MONOTONIC
is an alias for this clock.
Other systems define a
.Dv CLOCK_MONOTONIC_RAW
for a high-resolution clock which is not subject to adjustments.
.Dv CLOCK_HIGHRES
is not subject to time of day adjustments and thus can always be safely
used here.
.It Dv CLOCK_VIRTUAL
This clock represents the amount of CPU-time
.Pq in seconds and nanoseconds
that the calling thread has spent executing user code.
This is the same as the
.Fa pr_utime
member of the
.Vt prusage_t
and
.Fa pr_utime
member of the
.Vt lwpsinfo_t
structure discussed in
.Xr proc 5 .
.Pp
This clock cannot be set with
.Fn clock_settime
and has the same source as
.Xr gethrvtime 3C .
.It Dv CLOCK_THREAD_CPUTIME_ID
This clock is similar to
.Dv CLOCK_VIRTUAL ;
however, it also includes the system time of the calling thread in
addition to the user time.
.Pp
The system time is the same that is seen in the
.Fa pr_stime
member of the
.Vt lwpsinfo_t
structure discussed in
.Xr proc 5   .
System time includes both the system and trap microstates,
.Fa pr_stime
and
.Fa pr_ttime
of the
.Vt prusage_t
structure respectively.
.Pp
This clock cannot be set with
.Fn clock_settime
and it has an alias of
.Dv CLOCK_PROF .
.It Dv ClOCK_PROCESS_CPUTIME_ID
This clock represents the total CPU-time that the process
.Pq but not children
has spent in both user and system time for the calling process.
This is equivalent to the combination of the
.Fa pr_utime
and
.Fa pr_stime
members of the
.Vt psinfo_t
structure documented in
.Xr proc 5 .
.Pp
This clock is not settable with
.Fn clock_settime .
.El
.Sh RETURN VALUES
Upon successful completion,
.Sy 0
is returned.
Otherwise,
.Sy -1
is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn clock_settime ,
.Fn clock_gettime ,
and
.Fn clock_getres
functions will fail if:
.Bl -tag -width Er
.It Er EINVAL
The
.Fa clock_id
argument does not specify a known clock.
.It Er ENOSYS
The functions
.Fn \fBclock_settime ,
.Fn \fBclock_gettime ,
and
.Fn clock_getres
are not supported by this implementation.
Note, this error should not occur here.
.El
.Pp
The
.Fn clock_settime
function will fail if:
.Bl -tag -width Er
.It Er EINVAL
The
.Fa tp
argument is outside the range for the given clock ID; or the
.Fa tp
argument specified a nanosecond value less than zero or greater than or
equal to 1000 million.
.Pp
The clock specified by
.Fa clock_id
does not support being set.
.El
.Pp
The
.Fn clock_settime
function may fail if:
.Bl -tag -width Er
.It Er EPERM
The requesting process does not have the appropriate privilege to set the
specified clock.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Fn clock_gettime
is
.Sy Async-Signal-Safe
.Sh SEE ALSO
.Xr adjtime 2 ,
.Xr ntp_adjtime 2 ,
.Xr time 2 ,
.Xr ctime 3C ,
.Xr gethrtime 3C ,
.Xr gethrvtime 3C ,
.Xr settimeofday 3C ,
.Xr timer_gettime 3C ,
.Xr time.h 3HEAD ,
.Xr proc 5