Man Pages

timer_settime(2) - phpMan timer_settime(2) - phpMan

Command: man perldoc info search(apropos)  


TIMER_SETTIME(2)           Linux Programmer's Manual          TIMER_SETTIME(2)



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 sub-
       fields 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  cur-
       rently  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  indi-
       cate 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.22 of the Linux man-pages project.  A description of the project, and informa-
       tion about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                             2009-02-20                  TIMER_SETTIME(2)