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 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 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  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.  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  expira-
     tion,  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(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.