timer_settime

       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

DESCRIPTION
       timer_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-
       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 inter-
       val, 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_interval 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 a valid 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 ALSO
       timer_create(2), timer_settime(2), timer_getoverrun(2), time(7)

COLOPHON
       This  page  is  part of release 3.23 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)