illumos: manual page: clock

CLOCK_SETTIME(3C) Standard C Library Functions CLOCK_SETTIME(3C)

NAME

clock_settime, clock_gettime, clock_getres - high-resolution clock
operations

SYNOPSIS

#include <time.h>

int
clock_settime(clockid_t clock_id, const struct timespec *tp);

int
clock_gettime(clockid_t clock_id, struct timespec *tp);

int
clock_getres(clockid_t clock_id, struct timespec *res);

DESCRIPTION

The clock_settime() function sets the specified clock, clock_id, to the
value specified by 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.

The clock_gettime() function returns the current value tp for the specified
clock, clock_id.

The resolution of any clock can be obtained by calling clock_getres() Clock
resolutions are system-dependent and cannot be set by a process. If the
argument res is not NULL, the resolution of the specified clock is stored
in the location pointed to by res. If res is NULL, the clock resolution is
not returned. If the time argument of clock_settime() is not a multiple of
res, then the value is truncated to a multiple of res.

A clock may be system wide (that is, visible to all processes) or per-
process (measuring time that is meaningful only within a process).

The following clocks are supported in the system and defined by including
<time.h>:

CLOCK_REALTIME
This clock represents the realtime clock for the system. For this
clock, the values returned by clock_gettime() and specified by
clock_settime() represent the amount of time (in seconds and
nanoseconds) since the Epoch.

CLOCK_HIGHRES
This clock represents the non-adjustable, high-resolution clock for
the system. For this clock, the value returned by 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 adjtime(2), ntp_adjtime(2), settimeofday(3C), or
clock_settime(). The time source for this clock is the same as
that for gethrtime(3C).

It is not possible to set this clock with clock_settime().

CLOCK_MONOTONIC is an alias for this clock. Other systems define a
CLOCK_MONOTONIC_RAW for a high-resolution clock which is not
subject to adjustments. CLOCK_HIGHRES is not subject to time of
day adjustments and thus can always be safely used here.

CLOCK_VIRTUAL
This clock represents the amount of CPU-time (in seconds and
nanoseconds) that the calling thread has spent executing user code.
This is the same as the pr_utime member of the prusage_t and
pr_utime member of the lwpsinfo_t structure discussed in proc(5).

This clock cannot be set with clock_settime() and has the same
source as gethrvtime(3C).

CLOCK_THREAD_CPUTIME_ID
This clock is similar to CLOCK_VIRTUAL; however, it also includes
the system time of the calling thread in addition to the user time.

The system time is the same that is seen in the pr_stime member of
the lwpsinfo_t structure discussed in proc(5). System time
includes both the system and trap microstates, pr_stime and
pr_ttime of the prusage_t structure respectively.

This clock cannot be set with clock_settime() and it has an alias
of CLOCK_PROF.

ClOCK_PROCESS_CPUTIME_ID
This clock represents the total CPU-time that the process (but not
children) has spent in both user and system time for the calling
process. This is equivalent to the combination of the pr_utime and
pr_stime members of the psinfo_t structure documented in proc(5).

This clock is not settable with clock_settime().

RETURN VALUES

Upon successful completion, 0 is returned. Otherwise, -1 is returned and
errno is set to indicate the error.

ERRORS

The clock_settime(), clock_gettime(), and clock_getres() functions will
fail if:

EINVAL The clock_id argument does not specify a known clock.

ENOSYS The functions clock_settime(), clock_gettime(), and
clock_getres() are not supported by this implementation.
Note, this error should not occur here.

The clock_settime() function will fail if:

EINVAL The tp argument is outside the range for the given clock
ID; or the tp argument specified a nanosecond value less
than zero or greater than or equal to 1000 million.

The clock specified by clock_id does not support being
set.

The clock_settime() function may fail if:

EPERM The requesting process does not have the appropriate
privilege to set the specified clock.

INTERFACE STABILITY