1getitimer(2)                  System Calls Manual                 getitimer(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

91       On  success,  zero is returned.  On error, -1 is returned, and errno is
92       set to indicate the error.
93

ERRORS

95       EFAULT new_value, old_value, or curr_value is not valid a pointer.
96
97       EINVAL which is not one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF;
98              or  (since Linux 2.6.22) one of the tv_usec fields in the struc‐
99              ture pointed to by new_value contains a value outside the  range
100              [0, 999999].
101

VERSIONS

103       The standards are silent on the meaning of the call:
104
105           setitimer(which, NULL, &old_value);
106
107       Many  systems  (Solaris,  the  BSDs,  and perhaps others) treat this as
108       equivalent to:
109
110           getitimer(which, &old_value);
111
112       In Linux, this is treated as being equivalent to a call  in  which  the
113       new_value  fields  are zero; that is, the timer is disabled.  Don't use
114       this Linux misfeature: it is nonportable and unnecessary.
115

STANDARDS

117       POSIX.1-2008.
118

HISTORY

120       POSIX.1-2001, SVr4,  4.4BSD  (this  call  first  appeared  in  4.2BSD).
121       POSIX.1-2008  marks  getitimer() and setitimer() obsolete, recommending
122       the use of the POSIX timers  API  (timer_gettime(2),  timer_settime(2),
123       etc.) instead.
124

NOTES

126       Timers will never expire before the requested time, but may expire some
127       (short) time afterward, which depends on the  system  timer  resolution
128       and  on  the  system  load; see time(7).  (But see BUGS below.)  If the
129       timer expires while the process is active (always true for  ITIMER_VIR‐
130       TUAL), the signal will be delivered immediately when generated.
131
132       A  child  created  via  fork(2)  does not inherit its parent's interval
133       timers.  Interval timers are preserved across an execve(2).
134
135       POSIX.1 leaves the interaction between setitimer() and the three inter‐
136       faces alarm(2), sleep(3), and usleep(3) unspecified.
137

BUGS

139       The  generation and delivery of a signal are distinct, and only one in‐
140       stance of each of the  signals  listed  above  may  be  pending  for  a
141       process.  Under very heavy loading, an ITIMER_REAL timer may expire be‐
142       fore the signal from a previous expiration  has  been  delivered.   The
143       second signal in such an event will be lost.
144
145       Before Linux 2.6.16, timer values are represented in jiffies.  If a re‐
146       quest is made set a timer with a value whose jiffies representation ex‐
147       ceeds MAX_SEC_IN_JIFFIES (defined in include/linux/jiffies.h), then the
148       timer is silently truncated  to  this  ceiling  value.   On  Linux/i386
149       (where,  since  Linux 2.6.13, the default jiffy is 0.004 seconds), this
150       means that the ceiling value for a timer is approximately  99.42  days.
151       Since Linux 2.6.16, the kernel uses a different internal representation
152       for times, and this ceiling is removed.
153
154       On certain systems (including i386), Linux kernels before Linux  2.6.12
155       have  a bug which will produce premature timer expirations of up to one
156       jiffy under some circumstances.  This bug is fixed in Linux 2.6.12.
157
158       POSIX.1-2001 says that setitimer() should fail if a  tv_usec  value  is
159       specified that is outside of the range [0, 999999].  However, up to and
160       including Linux 2.6.21, Linux does  not  give  an  error,  but  instead
161       silently  adjusts  the corresponding seconds value for the timer.  From
162       Linux 2.6.22 onward, this nonconformance has been repaired: an improper
163       tv_usec value results in an EINVAL error.
164

SEE ALSO

166       gettimeofday(2), sigaction(2), signal(2), timer_create(2), timerfd_cre‐
167       ate(2), time(7)
168
169
170
171Linux man-pages 6.05              2023-05-03                      getitimer(2)
Impressum