1 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
2 .\" and Copyright (C) 2016, Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" Based on a similar page Copyright 1992 by Rick Faith
5 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
6 .\" May be freely distributed and modified
9 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
10 .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
11 .\" Noted MAX_SEC_IN_JIFFIES ceiling
13 .TH GETITIMER 2 2021-03-22 "Linux" "Linux Programmer's Manual"
15 getitimer, setitimer \- get or set value of an interval timer
18 .B #include <sys/time.h>
20 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
21 .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
22 .BI " struct itimerval *restrict " old_value );
25 These system calls provide access to interval timers, that is,
26 timers that initially expire at some point in the future,
27 and (optionally) at regular intervals after that.
28 When a timer expires, a signal is generated for the calling process,
29 and the timer is reset to the specified interval
30 (if the interval is nonzero).
32 Three types of timers\(emspecified via the
34 argument\(emare provided,
35 each of which counts against a different clock and
36 generates a different signal on timer expiration:
39 This timer counts down in real (i.e., wall clock) time.
45 This timer counts down against the user-mode CPU time consumed by the process.
46 (The measurement includes CPU time consumed by all threads in the process.)
52 This timer counts down against the total (i.e., both user and system)
53 CPU time consumed by the process.
54 (The measurement includes CPU time consumed by all threads in the process.)
61 this timer can be used to profile user and system CPU time
62 consumed by the process.
64 A process has only one of each of the three types of timers.
66 Timer values are defined by the following structures:
71 struct timeval it_interval; /* Interval for periodic timer */
72 struct timeval it_value; /* Time until next expiration */
76 time_t tv_sec; /* seconds */
77 suseconds_t tv_usec; /* microseconds */
85 places the current value of the timer specified by
87 in the buffer pointed to by
92 substructure is populated with the amount of time remaining until
93 the next expiration of the specified timer.
94 This value changes as the timer counts down, and will be reset to
96 when the timer expires.
99 are zero, then this timer is currently disarmed (inactive).
103 substructure is populated with the timer interval.
106 are zero, then this is a single-shot timer (i.e., it expires just once).
110 arms or disarms the timer specified by
112 by setting the timer to the value specified by
117 the buffer it points to is used to return the previous value of the timer
118 (i.e., the same information that is returned by
122 .IR new_value.it_value
124 then the timer is armed to initially expire at the specified time.
126 .IR new_value.it_value
127 are zero, then the timer is disarmed.
130 .IR new_value.it_interval
131 field specifies the new interval for the timer;
132 if both of its subfields are zero, the timer is single-shot.
134 On success, zero is returned.
135 On error, \-1 is returned, and
137 is set to indicate the error.
145 is not valid a pointer.
154 or (since Linux 2.6.22) one of the
156 fields in the structure pointed to by
158 contains a value outside the range 0 to 999999.
160 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
165 obsolete, recommending the use of the POSIX timers API
166 .RB ( timer_gettime (2),
167 .BR timer_settime (2),
170 Timers will never expire before the requested time,
171 but may expire some (short) time afterward, which depends
172 on the system timer resolution and on the system load; see
174 (But see BUGS below.)
175 If the timer expires while the process is active (always true for
176 .BR ITIMER_VIRTUAL ),
177 the signal will be delivered immediately when generated.
181 does not inherit its parent's interval timers.
182 Interval timers are preserved across an
188 and the three interfaces
195 The standards are silent on the meaning of the call:
197 setitimer(which, NULL, &old_value);
199 Many systems (Solaris, the BSDs, and perhaps others)
200 treat this as equivalent to:
202 getitimer(which, &old_value);
204 In Linux, this is treated as being equivalent to a call in which the
206 fields are zero; that is, the timer is disabled.
207 .IR "Don't use this Linux misfeature" :
208 it is nonportable and unnecessary.
210 The generation and delivery of a signal are distinct, and
211 only one instance of each of the signals listed above may be pending
213 Under very heavy loading, an
215 timer may expire before the signal from a previous expiration
217 The second signal in such an event will be lost.
219 On Linux kernels before 2.6.16, timer values are represented in jiffies.
220 If a request is made set a timer with a value whose jiffies
221 representation exceeds
222 .B MAX_SEC_IN_JIFFIES
224 .IR include/linux/jiffies.h ),
225 then the timer is silently truncated to this ceiling value.
226 On Linux/i386 (where, since Linux 2.6.13,
227 the default jiffy is 0.004 seconds),
228 this means that the ceiling value for a timer is
229 approximately 99.42 days.
231 the kernel uses a different internal representation for times,
232 and this ceiling is removed.
234 On certain systems (including i386),
235 Linux kernels before version 2.6.12 have a bug which will produce
236 premature timer expirations of up to one jiffy under some circumstances.
237 This bug is fixed in kernel 2.6.12.
238 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
239 .\" http://lkml.org/lkml/2005/7/1/165
241 POSIX.1-2001 says that
245 value is specified that is outside of the range 0 to 999999.
246 However, in kernels up to and including 2.6.21,
247 Linux does not give an error, but instead silently
248 adjusts the corresponding seconds value for the timer.
249 From kernel 2.6.22 onward,
250 this nonconformance has been repaired:
256 .\" Bugzilla report 25 Apr 2006:
257 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
258 .\" "setitimer() should reject noncanonical arguments"
260 .BR gettimeofday (2),
263 .BR timer_create (2),
264 .BR timerfd_create (2),