1 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
2 .\" Based on a similar page Copyright 1992 by Rick Faith
4 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
5 .\" May be freely distributed
8 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
9 .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
10 .\" Noted MAX_SEC_IN_JIFFIES ceiling
12 .TH GETITIMER 2 2012-10-01 "Linux" "Linux Programmer's Manual"
14 getitimer, setitimer \- get or set value of an interval timer
17 .B #include <sys/time.h>
19 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
21 .BI "int setitimer(int " which ", const struct itimerval *" new_value ,
22 .BI " struct itimerval *" old_value );
25 The system provides each process with three interval timers,
26 each decrementing in a distinct time domain.
27 When any timer expires, a signal is sent to the
28 process, and the timer (potentially) restarts.
31 decrements in real time, and delivers
36 decrements only when the process is executing, and delivers
41 decrements both when the process executes and when the system is executing
42 on behalf of the process.
45 this timer is usually used to profile the time spent by the
46 application in user and kernel space.
48 is delivered upon expiration.
50 Timer values are defined by the following structures:
56 struct timeval it_interval; /* next value */
57 struct timeval it_value; /* current value */
61 time_t tv_sec; /* seconds */
62 suseconds_t tv_usec; /* microseconds */
70 fills the structure pointed to by
72 with the current setting for the timer specified by
81 is set to the amount of time remaining on the timer, or zero if the timer
85 is set to the reset value.
89 sets the specified timer to the value in
93 is non-NULL, the old value of the timer is stored there.
97 to zero, generate a signal, and reset to
99 A timer which is set to zero
101 is zero or the timer expires and
109 are significant in determining the duration of a timer.
111 Timers will never expire before the requested time,
112 but may expire some (short) time afterward, which depends
113 on the system timer resolution and on the system load; see
115 (But see BUGS below.)
116 Upon expiration, a signal will be generated and the timer reset.
117 If the timer expires while the process is active (always true for
118 .BR ITIMER_VIRTUAL ),
119 the signal will be delivered immediately when generated.
121 delivery will be offset by a small time dependent on the system loading.
123 On success, zero is returned.
124 On error, \-1 is returned, and
126 is set appropriately.
134 is not valid a pointer.
143 or (since Linux 2.6.22) one of the
145 fields in the structure pointed to by
147 contains a value outside the range 0 to 999999.
149 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
154 obsolete, recommending the use of the POSIX timers API
155 .RB ( timer_gettime (2),
156 .BR timer_settime (2),
161 does not inherit its parent's interval timers.
162 Interval timers are preserved across an
168 and the three interfaces
175 The standards are silent on the meaning of the call:
177 setitimer(which, NULL, &old_value);
179 Many systems (Solaris, the BSDs, and perhaps others)
180 treat this as equivalent to:
182 getitimer(which, &old_value);
184 In Linux, this is treated as being equivalent to a call in which the
186 fields are zero; that is, the timer is disabled.
187 .IR "Don't use this Linux misfeature" :
188 it is nonportable and unnecessary.
190 The generation and delivery of a signal are distinct, and
191 only one instance of each of the signals listed above may be pending
193 Under very heavy loading, an
195 timer may expire before the signal from a previous expiration
197 The second signal in such an event will be lost.
199 On Linux kernels before 2.6.16, timer values are represented in jiffies.
200 If a request is made set a timer with a value whose jiffies
201 representation exceeds
202 .B MAX_SEC_IN_JIFFIES
204 .IR include/linux/jiffies.h ),
205 then the timer is silently truncated to this ceiling value.
206 On Linux/i386 (where, since Linux 2.6.13,
207 the default jiffy is 0.004 seconds),
208 this means that the ceiling value for a timer is
209 approximately 99.42 days.
211 the kernel uses a different internal representation for times,
212 and this ceiling is removed.
214 On certain systems (including i386),
215 Linux kernels before version 2.6.12 have a bug which will produce
216 premature timer expirations of up to one jiffy under some circumstances.
217 This bug is fixed in kernel 2.6.12.
218 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
219 .\" http://lkml.org/lkml/2005/7/1/165
221 POSIX.1-2001 says that
225 value is specified that is outside of the range 0 to 999999.
226 However, in kernels up to and including 2.6.21,
227 Linux does not give an error, but instead silently
228 adjusts the corresponding seconds value for the timer.
229 From kernel 2.6.22 onward,
230 this nonconformance has been repaired:
236 .\" Bugzilla report 25 Apr 2006:
237 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
238 .\" "setitimer() should reject noncanonical arguments"
240 .BR gettimeofday (2),
243 .BR timer_create (2),
244 .BR timerfd_create (2),
247 This page is part of release 3.68 of the Linux
250 A description of the project,
251 information about reporting bugs,
252 and the latest version of this page,
254 \%http://www.kernel.org/doc/man\-pages/.