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 .RI ( libc ", " \-lc )
21 .B #include <sys/time.h>
23 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
24 .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
25 .BI " struct itimerval *restrict " old_value );
28 These system calls provide access to interval timers, that is,
29 timers that initially expire at some point in the future,
30 and (optionally) at regular intervals after that.
31 When a timer expires, a signal is generated for the calling process,
32 and the timer is reset to the specified interval
33 (if the interval is nonzero).
35 Three types of timers\(emspecified via the
37 argument\(emare provided,
38 each of which counts against a different clock and
39 generates a different signal on timer expiration:
42 This timer counts down in real (i.e., wall clock) time.
48 This timer counts down against the user-mode CPU time consumed by the process.
49 (The measurement includes CPU time consumed by all threads in the process.)
55 This timer counts down against the total (i.e., both user and system)
56 CPU time consumed by the process.
57 (The measurement includes CPU time consumed by all threads in the process.)
64 this timer can be used to profile user and system CPU time
65 consumed by the process.
67 A process has only one of each of the three types of timers.
69 Timer values are defined by the following structures:
74 struct timeval it_interval; /* Interval for periodic timer */
75 struct timeval it_value; /* Time until next expiration */
79 time_t tv_sec; /* seconds */
80 suseconds_t tv_usec; /* microseconds */
88 places the current value of the timer specified by
90 in the buffer pointed to by
95 substructure is populated with the amount of time remaining until
96 the next expiration of the specified timer.
97 This value changes as the timer counts down, and will be reset to
99 when the timer expires.
102 are zero, then this timer is currently disarmed (inactive).
106 substructure is populated with the timer interval.
109 are zero, then this is a single-shot timer (i.e., it expires just once).
113 arms or disarms the timer specified by
115 by setting the timer to the value specified by
120 the buffer it points to is used to return the previous value of the timer
121 (i.e., the same information that is returned by
125 .I new_value.it_value
127 then the timer is armed to initially expire at the specified time.
129 .I new_value.it_value
130 are zero, then the timer is disarmed.
133 .I new_value.it_interval
134 field specifies the new interval for the timer;
135 if both of its subfields are zero, the timer is single-shot.
137 On success, zero is returned.
138 On error, \-1 is returned, and
140 is set to indicate the error.
148 is not valid a pointer.
157 or (since Linux 2.6.22) one of the
159 fields in the structure pointed to by
161 contains a value outside the range 0 to 999999.
163 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
168 obsolete, recommending the use of the POSIX timers API
169 .RB ( timer_gettime (2),
170 .BR timer_settime (2),
173 Timers will never expire before the requested time,
174 but may expire some (short) time afterward, which depends
175 on the system timer resolution and on the system load; see
177 (But see BUGS below.)
178 If the timer expires while the process is active (always true for
179 .BR ITIMER_VIRTUAL ),
180 the signal will be delivered immediately when generated.
184 does not inherit its parent's interval timers.
185 Interval timers are preserved across an
191 and the three interfaces
198 The standards are silent on the meaning of the call:
202 setitimer(which, NULL, &old_value);
206 Many systems (Solaris, the BSDs, and perhaps others)
207 treat this as equivalent to:
211 getitimer(which, &old_value);
215 In Linux, this is treated as being equivalent to a call in which the
217 fields are zero; that is, the timer is disabled.
218 .IR "Don't use this Linux misfeature" :
219 it is nonportable and unnecessary.
221 The generation and delivery of a signal are distinct, and
222 only one instance of each of the signals listed above may be pending
224 Under very heavy loading, an
226 timer may expire before the signal from a previous expiration
228 The second signal in such an event will be lost.
230 On Linux kernels before 2.6.16, timer values are represented in jiffies.
231 If a request is made set a timer with a value whose jiffies
232 representation exceeds
233 .B MAX_SEC_IN_JIFFIES
235 .IR include/linux/jiffies.h ),
236 then the timer is silently truncated to this ceiling value.
237 On Linux/i386 (where, since Linux 2.6.13,
238 the default jiffy is 0.004 seconds),
239 this means that the ceiling value for a timer is
240 approximately 99.42 days.
242 the kernel uses a different internal representation for times,
243 and this ceiling is removed.
245 On certain systems (including i386),
246 Linux kernels before version 2.6.12 have a bug which will produce
247 premature timer expirations of up to one jiffy under some circumstances.
248 This bug is fixed in kernel 2.6.12.
249 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
250 .\" http://lkml.org/lkml/2005/7/1/165
252 POSIX.1-2001 says that
256 value is specified that is outside of the range 0 to 999999.
257 However, in kernels up to and including 2.6.21,
258 Linux does not give an error, but instead silently
259 adjusts the corresponding seconds value for the timer.
260 From kernel 2.6.22 onward,
261 this nonconformance has been repaired:
267 .\" Bugzilla report 25 Apr 2006:
268 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
269 .\" "setitimer() should reject noncanonical arguments"
271 .BR gettimeofday (2),
274 .BR timer_create (2),
275 .BR timerfd_create (2),