NAME

timer_settime, timer_gettime, timer_getoverrun – high-resolution timer operations

SYNOPSIS

#include <time.h>

int timer_settime(timer_t timerid , int flags,

const struct itimerspec *value,

struct itimerspec *ovalue );

int timer_gettime(timer_t timerid,

struct itimerspec *value );

int timer_getoverrun(timer_t timerid );

struct itimerspec {

struct timespec it_interval; /* timer period */

struct timespec it_value; /* timer expiration */

};

struct timespec {

time_t tv_sec; /* seconds */

long tv_nsec; /* and nanoseconds */

};

DESCRIPTION

If is non-zero, timer_settime() arms the timer, timerid, to next expire after the time designated by value. Upon expiration, an application-specified notification (see timer_create()) is queued for the calling thread. If timerid was already armed when timer_settime() is called, this call resets the time until the next expiration using the specified value. If value is zero, then the timer is disarmed.

Time may be expressed as either an absolute or relative time. If flags is set to TIMER_RELTIME, then the timer will initially expire relative to when the call is made. If flags is set to TIMER_ABSTIME, then the initial expiration will be relative to 00:00 Universal Coordinated Time, January 1, 1970. If the specified (absolute) time has already passed, timer_settime() succeeds and the expiration notification is made.

If value->it_interval is non-zero, then timerid, will be a periodic timer, to be reloaded to expire every value->it_value seconds and nanoseconds. Otherwise, if value->it_interval is zero and value->it_value is non-zero, then timerid is a one-shot timer, which will expire only at the time specified by value->it_value.

If ovalue is not NULL, and timer timerid had previously been used, then timer_settime() will store the remaining time until the previous timer expires in the timer and the previous reload interval in ovalue. (If the previous timer was disarmed, ovalue will be set to zero). The values stored in ovalue by timer_settime() are the same values that would have been returned by a call to timer_gettime().

timer_gettime() stores the amount of time until the specified timer, timerid, expires into value.

Only a single signal can be queued to the thread for a given timer at any point in time. When a timer, for which a signal is still pending expires, (from a previous interval), no signal will be queued, and a timer overrun count will be incremented.

RETURN VALUES

timer_settime(), timer_gettime(), and timer_getoverrun() return 0 upon success. If these functions fail, they return -1 and set errno to indicate the error condition.

ERRORS

EINVAL

timerid does not correspond to a timer returned by timer_create().
The timer, timerid, had already been deleted by timer_delete().
timer_settime has an invalid member of a structure.

ENOSYS

The call is not supported.

SEE ALSO

clock_settime(), timer_create(), timer_delete()

NOTES

timer_getoverrun() is currently not supported and returns ENOSYS.