setitimer

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



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 itimer-
              val *ovalue);

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 {
                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 dis-
       abled.  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 gener-
       ated and the timer reset.  If the timer expires while  the  process  is
       active (always true for ITIMER_VIRT) the signal will be delivered imme-
       diately 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 outstanding event.  It's there-
       fore 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(2)