GETITIMER(R)        Linux Programmer's Manual        GETITIMER(R)



NAME
       getitimer,  setitimer  -  get  or set value of an interval
       timer

SYNOPSIS
       #include <sys/time.h>

       int getitimer(int which, struct itimerval *value);
       int setitimer(int which, const  struct  itimerval  *value,
              struct itimerval *ovalue);

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

       ITIMER_REAL    decrements  in  real  time,  and   delivers
                      SIGALRM upon expiration.

       ITIMER_VIRTUAL decrements only when the process is execut-
                      ing, and delivers  SIGVTALRM  upon  expira-
                      tion.

       ITIMER_PROF    decrements  both  when the process executes
                      and when the system is executing on  behalf
                      of  the  process.  Coupled with ITIMER_VIR-
                      TUAL, this timer is usually used to profile
                      the  time  spent by the application in user
                      and kernel  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 {
                long tv_sec;                /* seconds */
                long tv_usec;               /* microseconds */
            };

       The  function  getitimer  fills the structure indicated by
       value with the current setting for the timer indicated  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 indicated timer to
       the value in value.  If ovalue is nonzero, 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.

       Timers  will  never  expire  before  the  requested  time,
       instead expiring some  short,  constant  time  afterwards,
       dependent on the system timer resolution (currently 10ms).
       Upon expiration, a signal will be generated and the  timer
       reset.   If  the timer expires while the process is active
       (always true for ITIMER_VIRT) the signal will be delivered
       immediately  when  generated.  Otherwise the delivery will
       be offset by a small time dependent on the system loading.


RETURN VALUE
       On  success,  zero is returned.  On error, -1 is returned,
       and errno is set appropriately.

ERRORS
       EFAULT value or ovalue are not valid pointers.

       EINVAL which is not one of  ITIMER_REAL,  ITIMER_VIRT,  or
              ITIMER_PROF.

CONFORMING TO
       SVr4, 4.4BSD (This call first appeared in 4.2BSD).

SEE ALSO
       gettimeofday(y), sigaction(n), signal(l)

BUGS
       Under  Linux,  the generation and delivery of a signal are
       distinct, and there each signal is permitted only one out-
       standing  event.   It's  therefore  conceivable that under
       pathologically  heavy  loading,  ITIMER_REAL  will  expire
       before  the  signal  from  a  previous expiration has been
       delivered.  The second signal in such  an  event  will  be
       lost.



Linux 0.99.11               1993-08-05               GETITIMER(R)