setitimer

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 */
            };

       Getitimer(2)  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 ele-
       ment 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.  Setitimer(2)  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.

SEE ALSO

       gettimeofday(2), sigaction(2), signal(2).

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.