NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <time.h>int timer_settime(timer_t timerid, int flags, const struct itimerspec * value, struct itimerspec * ovalue);
The timer_settime function arms, resets, or disarms the timer specified by timerid . If the it_value member of the value argument is non-zero, the time of the next expiration is set accordingly (see next paragraph) and the timer is armed. If the timer was already armed, the time of the next expiration is modified accordingly. If the it_value member of value is zero, the timer is disarmed. Disarming or resetting a timer has no effect on either a pending notification, a concurrent execution of the notify function, or the timer's overrun count.
If the bit flag TIMER_ABSTIME is not set in the flags argument, the time of the next expiration is set to the interval specified in the it_value member of value relative to the current time. This means that the next expiration will occur value->it_value.tv_sec seconds plus value->it_value.tv_nsec nanoseconds after the timer_settime call. If the flag TIMER_ABSTIME is set in flags , the next expiration of the timer will occur when the clock associated with timerid reaches the value specified in the it_value member of value . If the time specified has already passed, timer_settime will succeed and the expiration notification will be sent.
If the timer is armed (or reset) by a call to timer_settime ) and the it_interval member of value is non-zero, a periodic (repetitive) timer is specified. At each expiration, the timer is immediately and automatically re-armed from value->it_interval . This value is treated as a relative interval regardless of the setting of the flags argument in the most recent timer_settime call.
Time values that are between two consecutive non-negative integer multiples of the resolution of the timer specified are rounded up to the larger multiple of the resolution. Any incremental quantity errors will not cause the timer to expire earlier than the rounded-up time value.
If the ovalue argument is not NULL, timer_settime will store, at the location referenced by ovalue , the previous amount of time remaining before the timer would have expired (zero if the timer was disarmed), and the previous reload value. The time remaining is stored as a relative interval even if the timer was armed with an absolute time. These values are stored before the state of the timer is changed in any way as a result of the current timer_settime call. The members of ovalue are subject to the resolution of the timer.
The timer_gettime function stores, at the location referenced by value , the amount of time remaining before the timer expires ( zero if the timer is disarmed), and the reload value specified in the most recent timer_settime call. The timer_gettime function is equivalent to timer_settime with a NULL value argument, and returns the identical information.
At most, a single notification is active for a given timer at any one time. If the timer expires while its corresponding notify function (see timer_create (3POSIX)) is still in execution from a previous notification, an overrun occurs. When the notify function subsequently returns, it will be re-invoked immediately, and the timer_getoverrun call may then be used to obtain the overrun count. An overrun count value pertains to a particular execution of the notification function; the value returned by timer_getoverrun does not change during that execution. The overrun count is defined as the number of timer expirations that occurred after the previous invocation of the notify function, but before that invocation returned. Thus, for a periodic timer, an overrun count equal to one indicates that the current invocation was delayed, but by less than the period interval. The timer_getoverrun function returns a maximum value of _POSIX_DELAYTIMER_MAX if the actual overrun count is greater than or equal to that value.
Because the notify function is executed by a thread, timely notification of timer expiration can be impeded by activity elsewhere on the system of higher priority than the handler thread (see timer_create (3POSIX))..
Upon successful completion, timer_settime and timer_gettime return zero, and timer_getoverrun returns the timer overrun count as described above. In case of error a value of -1 is returned by all three functions, and errno is set to indicate one of the following error conditions.
The timerid argument does not reference a currently valid timer, or the handler thread for the timer has been deleted. The flags argument contains an invalid value. The time specification in either the it_value member or the it_interval member of the value argument to timer_settime contains an invalid value.
A pointer argument contains an address outside the current actor's address space.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO