Digital

NAME

timer_settime, timer_gettime, − get or set the expiration time of the specified per-process timer (P1003.4/D10)

SYNOPSIS

#include <timers.h>

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

int timer_settime (
timer_t timerid ,
int abstime ,
const struct itimerspec ∗value ,
struct itimerspec ∗ovalue) ;

PARAMETERS

timerid The timer ID for the timer whose expiration time is set or returned. 

abstime Specifies whether the timer is to be an absolute or relative timer. 

value A pointer to an itimerspec data structure. 

ovalue A pointer to the itimerspec data structure into which the time remaining on the previous timer is returned. 

DESCRIPTION

The timer_gettime function returns the amount of time remaining in the current time interval before the expiration of the specified timer. The timer_settime function sets the expiration time of the specified per-process timer, determines if the timer is an absolute or relative timer, returns the time remaining (if any) on the previous specified timer, and arms the timer. 

Both the timer_gettime and timer_settime functions use an itimerspec structure, which consists of the following members:

struct timespec it_interval;

struct timespec it_value;

The itimerspec structure points to a timespec structure, which consists of the following members:

time_t tv_sec;

long tv_nsec;

Values specified for these members determine the duration of the timer intervals, as well as the start and end times. 

Use the timer_gettime function to determine whether a per-process timer is still active. If the timer is disabled, zero is returned. 

The timer_settime function sets the expiration time of the specified per-process timer and arms the timer. The abstime argument determines if the timer is an absolute or relative timer.  If the abstime argument is zero, the timer is a relative timer.  In this case, the time until the next timer expiration is set equal to the interval specified by the it_value member of value. The timer expires in the specified number of seconds and nanoseconds from when the call was made, that is, the timer is set relative to the current time. 

If abstime is non-zero, the timer is an absolute timer. In this case, the time until the next timer expiration is set equal to the difference between the absolute time specified by the it_value member of value and the current value of the clock associated with the timer ID. The timer expires when the clock reaches the value specified by it_value member. 

To disarm a timer specify a value of zero for the it_value member and call the timer_settime function. 

The reload value to the timer is set to the value specified by the it_interval member of value. If the it_interval is zero, a one-shot timer is specified. If the it_interval is non-zero, a periodic timer is specified. 

Note that the timer_getoverrun function is not supported for this release. 

RETURN VALUES

On a successful call, a value of 0 is returned. 

On an unsuccessful call, a value of −1 is returned and errno is set to indicate that an error occurred. 

ERRORS

The timer_gettime and timer_settime functions fail under the following conditions:

[EINVAL] The timerid argument does not correspond to an id returned bytimer_create, but not yet removed by timer_delete.  The timer_settime function can fail with this error, if a value structure specified a nanosecond value less than zero or greater than or equal to 1000 million. Or, a value structure specified a time that exceeds the maximum time for the specified timer. 

[ENOSYS] The configuration does not support P1003.4/D10 Timers.  Refer to the DEC OSF/1 Realtime Installation Guide for information on how to install the realtime software. 

RELATED INFORMATION

alarm(3), clock_gettime(3), timer_create(3), timer_getres(3)