NAME

SYNOPSIS

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_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

ERRORS

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

MT-LEVEL

SEE ALSO