'\"macro stdmacro
.Op c p a
.TH timer_settime 3C
.SH NAME
\f4timer_settime\f1 \- set the expiration time for a posix timer
.SH SYNOPSIS
.nf
\f4#include <time.h>\f1
.sp .6v
\f4int timer_settime (timer_t \f2timerid\fP, int \f2flags\fP, 
const struct itimerspec *\f2value\fP, struct itimerspec *\f2ovalue\fP);\f1
.fi
.SH DESCRIPTION
.P
\f4timer_settime\f1 sets the expiration time for the posix timer
named by \f2timerid\fP.  The \f4it_value\fP field of \f2value\fP is
used to specify the desired timer expiration time.  If the timer was previously
set and has not expired, then the timer is reset to the specified \f4it_value\fP.
In the event \f4it_value\fP is set to zero, the timer is disarmed.
.P
By default, posix timers interpret specified expiration times to be relative
to the time of the \f4timer_settime\f1 call.  Therefore, the timer will
expire in \f4it_value\fP nanoseconds from when the call is made.  This behavior,
however, may be altered using the \f2flags\fP parameter.  If the
\f4TIMER_ABSTIME\fP \f2flag\fP is set, then the timer will interpret the
specified expiration time to be absolute in respect to the clock associated
with \f2timerid\fP.  Hence, the timer will expire when the clock reaches the
specified \f4it_value\fP.  If \f4TIMER_ABSTIME\fP is selected and the specified
expiration time has already elapsed, the call will succeed and expiration
notification will be delivered.
.P
The periodic interval time for which subsequent timer expirations occur may
be set using the \f4it_interval\fP field of \f2value\fP.  If \f4it_interval\fP
is set to zero, then the timer will only expire once, as specified by
\f4it_value\fP.
.P
If \f2ovalue\fP is not set to \f4NULL\fP, then the previous
time remaining before \f2timerid\fP expiration is stored at memory address
\f2ovalue\fP.
.P
\f4timer_settime\f1 will fail if one or more of the following are true:
.TP 12
[EINVAL]
The \f2timerid\fP does not name a valid posix timer.
.TP
[EINVAL]
\f2value\fP contained a nanosecond value greater than 1000 million or
less than zero.
.TP
[EFAULT]
The address specified by either \f2value\fP or \f2ovalue\fP is outside
the range of the address space of the calling process. 
.SH SEE ALSO
timer_create(3C),
timer_delete(3C),
timer_getoverrun(3C),
timer_gettime(3C),
clock_settime(2),
clock_gettime(2),
clock_getres(2),
getitimer(2),
setiitimer(2)
.SH DIAGNOSTICS
Upon successful completion, a value of 0 is returned to the calling process. 
Otherwise, a value of -1 is returned and \f4errno\fP is set to indicate
the error.