Provided by: manpages-dev_3.21-1_all bug

NAME

       timer_settime, timer_gettime - arm/disarm and fetch state of POSIX per-
       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
       subfield  is  non-zero),  then timer_settime() 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
       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
       specified   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
       specifying TIMER_ABSTIME in flags, in which case new_value->it_value 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
       specified by new_value->it_value.  If the specified absolute  time  has
       already  passed,  then  the  timer expires immediately, and the overrun
       count (see timer_getoverrun(2)) will be set correctly.

       If the value of the CLOCK_REALTIME 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  CLOCK_REALTIME
       clock have no effect on relative timers based on that clock.

       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 the
       interval, 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 valid a 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.21 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/.