1GETITIMER(2)               Linux Programmer's Manual              GETITIMER(2)
2
3
4

NAME

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

SYNOPSIS

9       #include <sys/time.h>
10
11       int getitimer(int which, struct itimerval *curr_value);
12       int setitimer(int which, const struct itimerval *restrict new_value,
13                     struct itimerval *restrict old_value);
14

DESCRIPTION

16       These  system  calls provide access to interval timers, that is, timers
17       that initially expire at some point in the future, and (optionally)  at
18       regular intervals after that.  When a timer expires, a signal is gener‐
19       ated for the calling process, and the timer is reset to  the  specified
20       interval (if the interval is nonzero).
21
22       Three  types  of  timers—specified via the which argument—are provided,
23       each of which counts against a different clock and generates a  differ‐
24       ent signal on timer expiration:
25
26       ITIMER_REAL
27              This timer counts down in real (i.e., wall clock) time.  At each
28              expiration, a SIGALRM signal is generated.
29
30       ITIMER_VIRTUAL
31              This timer counts down against the user-mode CPU  time  consumed
32              by  the process.  (The measurement includes CPU time consumed by
33              all threads in the process.)  At each  expiration,  a  SIGVTALRM
34              signal is generated.
35
36       ITIMER_PROF
37              This  timer  counts  down against the total (i.e., both user and
38              system) CPU time consumed by the process.  (The measurement  in‐
39              cludes  CPU  time  consumed  by all threads in the process.)  At
40              each expiration, a SIGPROF signal is generated.
41
42              In conjunction with ITIMER_VIRTUAL, this timer can  be  used  to
43              profile user and system CPU time consumed by the process.
44
45       A process has only one of each of the three types of timers.
46
47       Timer values are defined by the following structures:
48
49           struct itimerval {
50               struct timeval it_interval; /* Interval for periodic timer */
51               struct timeval it_value;    /* Time until next expiration */
52           };
53
54           struct timeval {
55               time_t      tv_sec;         /* seconds */
56               suseconds_t tv_usec;        /* microseconds */
57           };
58
59   getitimer()
60       The  function  getitimer() places the current value of the timer speci‐
61       fied by which in the buffer pointed to by curr_value.
62
63       The it_value substructure is populated with the amount of time  remain‐
64       ing  until  the  next  expiration  of  the specified timer.  This value
65       changes as the timer counts down, and will be reset to it_interval when
66       the  timer  expires.   If  both  fields of it_value are zero, then this
67       timer is currently disarmed (inactive).
68
69       The it_interval substructure is populated with the timer interval.   If
70       both  fields  of it_interval are zero, then this is a single-shot timer
71       (i.e., it expires just once).
72
73   setitimer()
74       The function setitimer() arms or disarms the timer specified by  which,
75       by setting the timer to the value specified by new_value.  If old_value
76       is non-NULL, the buffer it points to is used  to  return  the  previous
77       value  of  the  timer  (i.e.,  the same information that is returned by