NAME
timersettime, timergettime - arm/disarm and fetch state of POSIX per- process timer SYNOPSIS
#include
int timersettime(timert timerid, int flags, const struct itimerspec *newvalue, struct itimerspec * oldvalue); int timergettime(timert timerid, struct itimerspec *currvalue); Link with -lrt. Feature Test Macro Requirements for glibc (see featuretestmacros(7)): timersettime(), timergettime(): POSIXCSOURCE >= 199309L DESCRIPTION timersettime() arms or disarms the timer identified by timerid. The newvalue argument is pointer to an itimerspec structure that specifies the new initial value and the new interval for the timer. The itimer‐ spec structure is defined as follows: struct timespec { timet tvsec; /* Seconds */ long tvnsec; /* Nanoseconds */ }; struct itimerspec { struct timespec itinterval; /* Timer interval */ struct timespec itvalue; /* 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 timercreate(2)
If newvalue->itvalue specifies a nonzero value (i.e., either subfield is nonzero), then timersettime() arms (starts) the timer, setting it to initially expire at the given time. (If the timer was already armed, then the previous settings are overwritten.) If
newvalue->itvalue specifies a zero value (i.e., both subfields are zero), then the timer is disarmed.
The newvalue->itinterval field specifies the period of the timer, in seconds and nanoseconds. If this field is nonzero, then each time that an armed timer expires, the timer is reloaded from the value specified
in newvalue->itinterval. If newvalue->itinterval specifies a zero value then the timer expires just once, at the time specified by itvalue. By default, the initial expiration time specified in
newvalue->itvalue 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 TIMERABSTIME in flags, in which case newvalue->itvalue 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 newvalue->itvalue. If the specified absolute time has already passed, then the timer expires immediately, and the overrun count (see timergetoverrun(2)) will be set correctly. If the value of the CLOCKREALTIME 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 CLOCKREALTIME clock have no effect on relative timers based on that clock. If oldvalue is not NULL, then it points to a buffer that is used to
return the previous interval of the timer (in oldvalue->itinterval) and the amount of time until the timer would previously have next
expired (in oldvalue->itvalue). timergettime() returns the time until next expiration, and the inter‐ val, for the timer specified by timerid, in the buffer pointed to by currvalue. The time remaining until the next timer expiration is
returned in currvalue->itvalue; this is always a relative value, regardless of whether the TIMERABSTIME flag was used when arming the
timer. If the value returned in currvalue->itvalue is zero, then the timer is currently disarmed. The timer interval is returned in
currvalue->itinterval. If the value returned in
currvalue->itinterval is zero, then this is a "one-shot" timer. RETURN VALUE
On success, timersettime() and timergettime() 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 newvalue, oldvalue, or currvalue is not a valid pointer. EINVAL timerid is invalid. timersettime() may fail with the following errors: EINVAL newvalue.itvalue is negative; or newvalue.itvalue.tvnsec 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 timercreate(2). SEE ALSO timercreate(2), timergetoverrun(2), time(7) COLOPHON
This page is part of release 3.53 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 2012-10-15 TIMERSETTIME(2)