timer_settime(3)timer_settime(3)NAME
timer_settime, timer_gettime - Obtains or sets the expiration time of
the specified per-process timer (P1003.1b)
SYNOPSIS
#include <time.h>
int timer_gettime (
timer_t timerid,
struct itimerspec *value);
int timer_settime (
timer_t timerid,
int flags,
const struct itimerspec *value,
struct itimerspec *ovalue);
LIBRARY
Realtime Library (librt.so, librt.a)
PARAMETERS
Specifies the timer ID for the timer whose expiration time is set or
returned. Specifies whether the timer is to be an absolute or relative
timer. Specifies a pointer to an itimerspec data structure. Specifies
a pointer to the itimerspec data structure into which the time remain‐
ing 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 whether 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: timespec it_inter‐
val; timespec it_value;
Each timespec structure consists of the following members: tv_sec;
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 TIMER_ABSTIME option deter‐
mines whether the timer is an absolute or relative timer. If the
TIMER_ABSTIME option is not set (options=0), the timer is set relative
to the current time (a relative timer). In this case, the time until
the next timer expiration equals 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.
If the TIMER_ABSTIME option is set, the timer is set with a specified
starting time (an absolute timer). In this case, the time until the
next timer expiration equals 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.
Times that are between two consecutive non-negative integer multiples
of the resolution are rounded up to the larger multiple of the resolu‐
tion.
To disarm a timer, specify a value of 0 (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.
RETURN VALUES
On a successful call to the timer_gettime and timer_settime functions,
a value of 0 (zero) 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
condition: The timerid argument does not correspond to an ID returned
by timer_create and not yet removed by timer_delete. Additionally, 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.
SEE ALSO
Functions: clock_gettime(3), timer_create(3)
Guide to Realtime Programming
timer_settime(3)
