Tribblix: 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