TIMER_SETTIME(3)

NAME
timer_settime - set the expiration time for a POSIX timer

SYNOPSIS
cc [ flag ... ] file -lrt [ library ... ]

#include <time.h>

int timer_settime(timer_t timer_id, int flags, const struct itimerspec *new_setting, const struct itimerspec *old_setting);

DESCRIPTION
timer_settime sets the expiration time for the timer specified by timer_id, thus marking it active. The it_value field of new_value specifies the expiration time in nanoseconds. If the timer is already set then it is reset to the new value specified by it_value. If it_value is zero, the timer is disabled.

The default behavior is to interpret the specified expiration time as relative to the current time as of the call. The TIMER_ABSTIME flag specified in flags will modify this behavior to make the value specified by it_value absolute with respect to the clock associated with timer_id. Thus, the timer will expire when the clock reaches the value specified by it_value. If TIMER_ABSTIME specifies a value which has already elapsed, the call will succeed and the timer will immediately expire.

The interval at which the timer will subsequently expire is specified by it_interval. If it_interval is set to zero, the timer will expire only once, as specified by it_value. In order to prevent timer intervals from overloading the system, the system prevents setting it_interval below a minimum value. This minimum value is determined by an overload test, the results of which are printed on boot.

If old_value is non-NULL, the previous time remaining before expiration is stored in the itimerspec structure pointed to by old_value.

Changes to the clock value (e.g. via clock_settime(3)) will not affect any timers.

RETURN VALUE
On success, timer_settime returns the value 0 and the timer specified by timer_id is set as specified by new_value. If old_value is non-NULL, it contains the previous time remaining before expiration.

On failure, timer_settime returns the value -1 and errno is set appropriately.

ERRORS

EFAULT
    A specified memory address is outside the address range of the calling process.

EINVAL
    timer_id is not a valid, owned (by the process) timer or new_value has a negative second or nano second value or the nano second value is greater than or equal to 1,000 million or the resulting expire time is too large for the system. Values "too large" are those that can not be converted to "jiffies" from "now" with a resulting value less than MAX_LONG.

CONFORMING TO
POSIX 1003.1b (formerly POSIX.4) as ammended by POSIX 1003.1j-2000.

SEE ALSO
clock_getres(3), clock_gettime(3), clock_settime(3), clock_nanosleep(3), timer_create(3), timer_delete(3), timer_gettime(3), timer_getoverrun(3)

IEEE 1003.1b-1993 (POSIX.1b standard, formerly POSIX.4), Section 14 (Clocks and Timers).