timer_getoverrun(), timer_gettime(), timer_settime()

manipulate per-process timers 

Realtime Functions


SYNOPSIS

#include <time.h>

int timer_getoverrun(timer_t timerid);

int timer_gettime(timer_t timerid, struct itimerspec *value);

int timer_settime(timer_t timerid, int flags, const struct itimerspec *value, struct itimerspec *ovalue);


DESCRIPTION

The timer_gettime() function retrieves the amount of time remaining until the timer specified by timerid expires. If the timer is disarmed, this value is 0. stores this value along with the reload value of the timer in the itimerspec structure pointed to by value. The retrieved time remaining is stored in the it_value member of this structure, while the reload value of the timer (as set by set_time()) is stored in the it_interval member.

The timer_settime() function sets the time until expiration for the timer specified by timerid. To do so, it uses the value of the it_value member of the itimerspec structure pointed to by value. When it_value is 0, the timer is disarmed; otherwise, it is armed. The timer_settime() function does not reset overrun counts.

Whether or not the TIMER_ABSTIME is set in flags determines whether timer_settime() interprets the value of the it_value as an absolute time (that is, a specific time) or a relative time (that is, a time interval). When TIMER_ABSTIME is set, timer_settime() sets the time until expiration of timerid to the difference between time specified by it_value and the current time. However, if the time specified by it_value has already passed, the function succeed and notification of the timer expiration is made. When TIMER_ABSTIME is not set, timer_settime() sets the time until expiration of timerid to the it_value value.

timer_settime() sets the reload value of timerid to the value of the it_interval member of value. When this value is non-zero, it indicates that the timer is a periodic (or repetitive) timer.

When a time value is not a multiple of the specified timer's resolution, that time value is rounded up to the nearest multiple.

When ovalue is not a null pointer, timer_settime() stores, in the location pointed to, the previous remaining time before expiration for timerid along with the previous reload value for that timer.

The timer_getoverrun() function returns the timer expiration overrun count for the timer specified by timerid. A timer overrun occurs when a timer expires and still has a pending signal. No additional signal is queued because a given timer may only have one signal queued to the process. The timer overrun expiration count is the number of additional timer expirations that occurred between when the signal was queued and when it was delivered or accepted. This count has a maximum of {DELAYTIMER_MAX}. On the NuTCRACKER Platform DELAYTIMER_MAX is set to INT_MAX, allowing this function to count a fairly large number of overruns. When the specified timer is uninitialized, timer_getoverrun() returns 0.


PARAMETERS

flags 

Contains the TIMER_ABSTIME flag which determines whether it_value member of value is treated as an absolute or relative time value.

ovalue 

Points to an itimerspec structure where timer_settime() stores the previous time remaining until expiration and previous reload value.

timerid 

Specifies a timer ID.

value 

Points to an itimerspec structure which contains the values retrieved by timer_gettime() or the values to be set by timer_settime().


RETURN VALUES

When successful, timer_gettime() and timer_settime() return 0 while timer_getoverrun() returns the timer expiration overrun count as described in the DESCRIPTION section.

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

EFAULT 

The timerid argument to timer_gettime() or timer_settime() is a bad pointer.

EINVAL 

The timerid argument is not a valid timer ID or the value argument of timer_settime() pointed to a structure that did not contain a valid time value.


CONFORMANCE

UNIX 03.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

The flag TIMER_RESUME can be used to configure timer_settime() to wake the system from a suspended power conservation mode when the specified interval expires.


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:
_NutConf(), clock_getres(), timer_create()

Miscellaneous:
struct itimerspec


PTC MKS Toolkit 10.3 Documentation Build 39.