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 or new_value contain an invalid value.

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).