clock_getres, clock_gettime, and clock_settime Subroutine

Purpose

Clock and timer functions.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>

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

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

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

Description

The clock_getres subroutine returns the resolution of any clock. Clock resolutions are implementation-defined and cannot be set by a process. If the res parameter is not NULL, the resolution of the specified clock is stored in the location pointed to by the res parameter. If the res parameter is NULL, the clock resolution is not returned. If the time parameter of the clock_settime subroutine is not a multiple of the res parameter, the value is truncated to a multiple of the res parameter.

The clock_gettime subroutine returns the current value, tp, for the specified clock, clock_id.

The clock_settime subroutine sets the specified clock, clock_id, to the value specified by the tp parameter. Time values that are between two consecutive non-negative integer multiples of the resolution of the specified clock will be truncated down to the smaller multiple of the resolution.

A clock may be system-wide (visible to all processes) or per-process (measuring time that is meaningful only within a process). All implementations support a clock_id of CLOCK_REALTIME as defined in the time.h file. This clock represents the Realtime clock for the system. For this clock the values returned by the clock_gettime subroutine and specified by the clock_settime subroutine represent the amount of time (in seconds and nanoseconds) since the epoch.

If the value of the CLOCK_REALTIME clock is set through the clock_settime subroutine, the new value of the clock is used to determine the time of expiration for absolute time services based upon the CLOCK_REALTIME clock. This applies to the time at which armed absolute timers expire. If the absolute time requested at the invocation of such a time service is before the new value of the clock, the time service expires immediately as if the clock had reached the requested time normally.

Setting the value of the CLOCK_REALTIME clock through the clock_settime subroutine has no effect on threads that are blocked waiting for a relative time service based upon this clock, including the nanosleep subroutine; nor on the expiration of relative timers based upon this clock. Consequently, these time services expire when the requested relative interval elapses, independently of the new or old value of the clock.

A clock_id of CLOCK_MONOTONIC is defined in the time.h file. This clock represents the monotonic clock for the system. For this clock, the value returned by the clock_gettime subroutine represents the amount of time (in seconds and nanoseconds) since an unspecified point in the past. This point does not change after system start time (for example, this clock cannot have backward jumps). The value of the CLOCK_MONOTONIC clock cannot be set through the clock_settime subroutine. This subroutine fails if it is invoked with a clock_id parameter of CLOCK_MONOTONIC.

The calling process should have SYS_OPER authority to set the value of the CLOCK_REALTIME clock.

Process CPU-time clocks are supported by the system. For these clocks, the values returned by clock_gettime and specified by clock_settime represent the amount of execution time of the process associated with the clock. Clockid_t values for CPU-time clocks are obtained by calling clock_getcpuclockid. A special clockid_t value, CLOCK_PROCESS_CPUTIME_ID, is defined in the time.h file. This value represents the CPU-time clock of the calling process when one of the clock_* or timer_* functions is called.

To get or set the value of a CPU-time clock, the calling process must have root permissions or have the same effective or real user ID as the process that owns the targeted CPU-time clock. The same rule applies to a process that tries to get the resolution of a CPU-time clock.

Thread CPU-time clocks are supported by the system. For these clocks, the values returned by clock_gettime and specified by clock_settime represent the amount of execution time of the thread associated with the clock. Clockid_t values for thread CPU-time clocks are obtained by calling the pthread_getcpuclockid subroutine. A special clockid_t value, CLOCK_THREAD_CPUTIME_ID, is defined in the time.h file. This value represents the thread CPU-time clock of the calling thread when one of the clock_*() or timer_* functions is called.

To get or set the value of a thread CPU-time clock, the calling thread must be a thread in the same process as the one that owns the targeted thread CPU-time clock. The same rule applies to a thread that tries to get the resolution of a thread CPU-time clock.

Parameters

Return Values

If successful, 0 is returned. If unsuccessful, -1 is returned, and errno will be set to indicate the error.

Error Codes