setitimer


SYNOPSIS
       #include <sys/time.h>

       int getitimer(int which, struct itimerval *curr_value);
       int setitimer(int which, const struct itimerval *new_value,
                     struct itimerval *old_value);

DESCRIPTION
       The  system  provides  each  process  with  three interval timers, each
       decrementing in a distinct time domain.  When any timer expires, a sig-
       nal is sent to the process, and the timer (potentially) restarts.

       ITIMER_REAL    decrements in real time, and delivers SIGALRM upon expi-
                      ration.

       ITIMER_VIRTUAL decrements only  when  the  process  is  executing,  and
                      delivers SIGVTALRM upon expiration.

       ITIMER_PROF    decrements  both  when the process executes and when the
                      system is executing on behalf of the  process.   Coupled
                      with  ITIMER_VIRTUAL, this timer is usually used to pro-
                      file the time spent by the application in user and  ker-
                      nel space.  SIGPROF is delivered upon expiration.

       Timer values are defined by the following structures:

           struct itimerval {
               struct timeval it_interval; /* next value */
               struct timeval it_value;    /* current value */
           };

           struct timeval {
               time_t      tv_sec;         /* seconds */
               suseconds_t tv_usec;        /* microseconds */
           };

       The  function  getitimer() fills the structure pointed to by curr_value
       with the current setting for the  timer  specified  by  which  (one  of
       ITIMER_REAL,  ITIMER_VIRTUAL, or ITIMER_PROF).  The element it_value is
       set to the amount of time remaining on the timer, or zero if the  timer
       is disabled.  Similarly, it_interval is set to the reset value.

       The  function  setitimer()  sets  the  specified  timer to the value in
       new_value.  If old_value is non-NULL, the old value  of  the  timer  is
       stored there.

       Timers decrement from it_value to zero, generate a signal, and reset to
       it_interval.  A timer which is set to zero (it_value  is  zero  or  the
       timer expires and it_interval is zero) stops.

       Both  tv_sec and tv_usec are significant in determining the duration of
       a timer.


ERRORS
       EFAULT new_value, old_value, or curr_value is not valid a pointer.

       EINVAL which is not one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF;
              or  (since Linux 2.6.22) one of the tv_usec fields in the struc-
              ture pointed to by new_value contains a value outside the  range
              0 to 999999.

CONFORMING TO
       POSIX.1-2001,  SVr4,  4.4BSD  (this  call  first  appeared  in 4.2BSD).
       POSIX.1-2008 marks getitimer() and setitimer()  obsolete,  recommending
       the  use  of  the POSIX timers API (timer_gettime(2), timer_settime(2),
       etc.) instead.

NOTES
       A child created via fork(2) does  not  inherit  its  parent's  interval
       timers.  Interval timers are preserved across an execve(2).

       POSIX.1 leaves the interaction between setitimer() and the three inter-
       faces alarm(2), sleep(3), and usleep(3) unspecified.

       The standards are silent on the meaning of the call:

           setitimer(which, NULL, &old_value);

       Many systems (Solaris, the BSDs, and  perhaps  others)  treat  this  as
       equivalent to:

           getitimer(which, &old_value);

       In  Linux,  this  is treated as being equivalent to a call in which the
       new_value fields are zero; that is, the timer is disabled.   Don't  use
       this Linux misfeature: it is nonportable and unnecessary.

BUGS
       The  generation  and  delivery  of  a signal are distinct, and only one
       instance of each of the signals listed  above  may  be  pending  for  a
       process.   Under  very  heavy  loading, an ITIMER_REAL timer may expire
       before the signal from a previous expiration has been  delivered.   The
       second signal in such an event will be lost.

       On  Linux  kernels  before  2.6.16,  timer  values  are  represented in
       jiffies.  If a request is made set a timer with a value  whose  jiffies
       representation      exceeds      MAX_SEC_IN_JIFFIES     (defined     in
       include/linux/jiffies.h), then the timer is silently truncated to  this
       ceiling  value.   On Linux/i386 (where, since Linux 2.6.13, the default
       jiffy is 0.004 seconds), this means that the ceiling value for a  timer
       is  approximately  99.42  days.   Since Linux 2.6.16, the kernel uses a
       different internal  representation  for  times,  and  this  ceiling  is
       removed.

       On  certain  systems  (including  i386),  Linux  kernels before version
       2.6.12 have a bug which will produce premature timer expirations of  up
       ate(2), time(7)

COLOPHON
       This page is part of release 3.54 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                             2012-10-01                      GETITIMER(2)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.