clock_getres(), clock_gettime(), clock_settime()

clock and timer functions 

Realtime Function

SYNOPSIS

#include <time.h>

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

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

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

DESCRIPTION

The clock_getres() function returns the resolution of the clock specified by clock_id and places it in the location indicated by res. However, if res is NULL, no resolution is returned.

The clock_gettime() function returns the current value of the clock specified by clock_id and places it in the location pointed to by tp.

The clock_settime() function sets the clock specified by clock_id to the time pointed to by tp. When tp is not a multiple of the specified clock's resolution, the largest multiple of tp that is less than tp is used instead.

There are two types of clocks: system-wide clocks that all processes can access and per-process clocks that only have meaning within that process. Details on available clocks for the NuTCRACKER Platform can be found on the api_intro reference page.

The CLOCK_REALTIME clock is the system realtime clock as defined in time.h. When the clock_gettime() and clock_settime() functions specify CLOCK_REALTIME as the clock_id value, the time value to be retrieved or set is the amount of time in seconds and milliseconds since the Epoch (January 1, 1970).

When clock_settime() is used to set the CLOCK_REALTIME clock, this new value determines when absolute time services (including armed absolute timers) based on this clock expire. If the new value is after the absolute time specified when an absolute time service was started, the time service expires immediately.

Using clock_settime() to set the CLOCK_REALTIME clock does not affect the expiration of relative timers based on this clock or threads (including sleep()) that are blocked waiting for such a time service. As a result, relative time services only expire when the time interval specified at invocation has passed.

Additionally, any new value for the CLOCK_REALTIME clock set with the clock_settime() function determines the time at which the system awakens a thread blocked on an absolute clock_nanosleep() call based on this clock. If the new value is after the absolute time specified when the call was invoked, the call returns immediately. Setting a new value in this way has no effect on a thread blocked on a relative nanosleep() call.

Finally, on the NuTCRACKER Platform, calling clock_settime() to set CLOCK_REALTIME automatically updates any timers created by timer_settime() or clock_nanosleep() that use absolute time (that is, have the TIMER_ABSTIME flag set). These timers are updated to use the new system time.

PARAMETERS

clock_id 

Specifies the clock on which the clock_getres(), clock_gettime(), or clock_settime() function operates.

Available clock ID values for the NuTCRACKER Platform can be found on the api_intro reference page. Of these, only CLOCK_REALTIME can be used with the clock_settime() function.

res 

Points to the location where clock_getres() stores the clock resolution retrieved.

tp 

Points to a timespec structure which is used to store the time value retrieved with clock_gettime() or which contains the new time value to be set with clock_settime().

RETURN VALUES

When successful, these function return 0.

Otherwise, these functions return -1 and set errno to the one of the following:

EFAULT 

The clock_id parameter is a bad pointer.

EINVAL 

The clock_id parameter does not identify a known clock or an invalid value was specified for tp for clock_settime().

EPERM 

The process calling clock_settime() lacks the appropriate privilege to set the specified clock.

CONFORMANCE

UNIX 03.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

On the NuTCRACKER Platform, clock_settime() is implemented using the Win32 SetSystemTime() API. This API has millisecond resolution.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

api_intro

Functions:
clock_getcpuclockid(), clock_nanosleep(), ctime(), mq_timedreceive(), mq_timedsend(), nanosleep(), pthread_mutex_timedlock(), sem_timedwait(), time(), timer_create(), timer_getoverrun()

Miscellaneous:
struct timespec

PTC MKS Toolkit 10.4 Documentation Build 39.