TIMER_SETTIME(2) Linux Programmer's Manual TIMER_SETTIME(2)NAME
timer_settime, timer_gettime - arm/disarm and fetch state of POSIX per-
process timer
SYNOPSIS
#include <time.h>
int timer_settime(timer_t timerid, int flags,
const struct itimerspec *new_value,
struct itimerspec * old_value);
int timer_gettime(timer_t timerid, struct itimerspec *curr_value);
Link with -lrt.
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
timer_settime(), timer_gettime(): _POSIX_C_SOURCE >= 199309
DESCRIPTIONtimer_settime() arms or disarms the timer identified by timerid. The
new_value argument is an itimerspec structure that specifies the new
initial value and the new interval for the timer. The itimerspec
structure is defined as follows:
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds */
};
struct itimerspec {
struct timespec it_interval; /* Timer interval */
struct timespec it_value; /* Initial expiration */
};
Each of the substructures of the itimerspec structure is a timespec
structure that allows a time value to be specified in seconds and
nanoseconds. These time values are measured according to the clock
that was specified when the timer was created by timer_create()
If new_value->it_value specifies a non-zero value (i.e., either sub‐
field is non-zero), then timer_settime() arms (starts) the timer, set‐
ting it to initially expire at the given time. (If the timer was
already armed, then the previous settings are overwritten.) If
new_value->it_value specifies a zero value (i.e., both subfields are
zero), then the timer is disarmed.
The new_value->it_interval field specifies the period of the timer, in
seconds and nanoseconds. If this field is non-zero, then each time
that an armed timer expires, the timer is reloaded from the value spec‐
ified in new_value->it_interval. If new_value->it_interval specifies a
zero value then the timer expires just once, at the time specified by
it_value.
By default, the initial expiration time specified in
new_value->it_value is interpreted relative to the current time on the
timer's clock at the time of the call. This can be modified by speci‐
fying TIMER_ABSTIME in flags, in which case new_value->it_value is
interpreted as an absolute value as measured on the timer's clock; that
is, the timer will expire when the clock value reaches the value speci‐
fied by new_value->it_value. If the specified absolute time has
already passed, then the timer expires immediately, and the overrun
count (see timer_getoverrun(2)) will be set correctly.
If the value of the CLOCK_REALTIME clock is adjusted while an absolute
timer based on that clock is armed, then the expiration of the timer
will be appropriately adjusted. Adjustments to the CLOCK_REALTIME
clock have no effect on relative timers based on that clock.
If old_value is not NULL, then it returns the previous interval of the
timer (in old_value->it_interval) and the amount of time until the
timer would previously have next expired (in old_value->it_value).
timer_gettime() returns the time until next expiration, and the the
interval, for the timer specified by timerid, in the buffer pointed to
by curr_value. The time remaining until the next timer expiration is
returned in curr_value.it_value; this is always a relative value,
regardless of whether the TIMER_ABSTIME flag was used when arming the
timer. If the value returned in curr_value.it_value is zero, then the
timer is currently disarmed. The timer interval is returned in
curr_value.it_interval. If the value returned in curr_value.it_inter‐
val is zero, then this is a "one-shot" timer.
RETURN VALUE
On success, timer_settime() and timer_gettime() return 0. On error, -1
is returned, and errno is set to indicate the error.
ERRORS
These functions may fail with the following errors:
EFAULT new_value, old_value, or curr_value is not valid a pointer.
EINVAL timerid is invalid.
timer_settime() may fail with the following errors:
EINVAL new_value.it_value is negative; or new_value.it_value.tv_nsec is
negative or greater than 999,999,999.
VERSIONS
These system calls are available since Linux 2.6.
CONFORMING TO
POSIX.1-2001
EXAMPLE
See timer_create(2).
SEE ALSOtimer_create(2), timer_settime(2), timer_getoverrun(2), time(7)COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2009-02-20 TIMER_SETTIME(2)