Provided by: manpages-dev_2.17-1_all bug

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  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
                      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 non-zero, 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, but may expire some
       (short) time afterwards, which depends on the system  timer  resolution
       and  on  the  system  load.   (But see BUGS below.)  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

       POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).

SEE ALSO

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

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, 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 2.6 on x86
       (where a jiffy is 0.001 seconds), this means that the ceiling value for
       a timer is approximately 24.86 days.

       On certain systems (including x86), Linux kernels before version 2.6.12
       have a bug which will produce premature timer expirations of up to  one
       jiffy under some circumstances.  This bug is fixed in kernel 2.6.12.

       POSIX.1  says  that  setitimer()  should  fail  if  a  tv_usec value is
       specified that is outside of the range 0  to  999999.   However,  Linux
       does  not give an error, but instead silently adjusts the corresponding
       seconds value for the timer.