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 2014-07-08 "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 a timer expires, a signal is sent to the
28 process, and the timer is reset to the specified interval (if nonzero).
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; /* Interval for periodic timer */
57 struct timeval it_value; /* Time until next expiration */
61 time_t tv_sec; /* seconds */
62 suseconds_t tv_usec; /* microseconds */
70 fills the structure pointed to by
72 with the current value
73 (i.e., the amount of time remaining until the next expiration)
74 of the timer specified by
81 The subfields of the field
83 are set to the amount of time remaining on the timer, or zero if the timer
87 field is set to the timer interval (period);
88 a value of zero returned in (both subfields of) this field indicates
89 that this is a single-shot timer.
93 sets the specified timer to the value in
97 is non-NULL, the old value of the timer
98 (i.e., the same information as returned by
102 Timers decrement from
104 to zero, generate a signal, and reset to
106 A timer which is set to zero
108 is zero or the timer expires and
116 are significant in determining the duration of a timer.
118 Timers will never expire before the requested time,
119 but may expire some (short) time afterward, which depends
120 on the system timer resolution and on the system load; see
122 (But see BUGS below.)
123 Upon expiration, a signal will be generated and the timer reset.
124 If the timer expires while the process is active (always true for
125 .BR ITIMER_VIRTUAL ),
126 the signal will be delivered immediately when generated.
128 delivery will be offset by a small time dependent on the system loading.
130 On success, zero is returned.
131 On error, \-1 is returned, and
133 is set appropriately.
141 is not valid a pointer.
150 or (since Linux 2.6.22) one of the
152 fields in the structure pointed to by
154 contains a value outside the range 0 to 999999.
156 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
161 obsolete, recommending the use of the POSIX timers API
162 .RB ( timer_gettime (2),
163 .BR timer_settime (2),
168 does not inherit its parent's interval timers.
169 Interval timers are preserved across an
175 and the three interfaces
182 The standards are silent on the meaning of the call:
184 setitimer(which, NULL, &old_value);
186 Many systems (Solaris, the BSDs, and perhaps others)
187 treat this as equivalent to:
189 getitimer(which, &old_value);
191 In Linux, this is treated as being equivalent to a call in which the
193 fields are zero; that is, the timer is disabled.
194 .IR "Don't use this Linux misfeature" :
195 it is nonportable and unnecessary.
197 The generation and delivery of a signal are distinct, and
198 only one instance of each of the signals listed above may be pending
200 Under very heavy loading, an
202 timer may expire before the signal from a previous expiration
204 The second signal in such an event will be lost.
206 On Linux kernels before 2.6.16, timer values are represented in jiffies.
207 If a request is made set a timer with a value whose jiffies
208 representation exceeds
209 .B MAX_SEC_IN_JIFFIES
211 .IR include/linux/jiffies.h ),
212 then the timer is silently truncated to this ceiling value.
213 On Linux/i386 (where, since Linux 2.6.13,
214 the default jiffy is 0.004 seconds),
215 this means that the ceiling value for a timer is
216 approximately 99.42 days.
218 the kernel uses a different internal representation for times,
219 and this ceiling is removed.
221 On certain systems (including i386),
222 Linux kernels before version 2.6.12 have a bug which will produce
223 premature timer expirations of up to one jiffy under some circumstances.
224 This bug is fixed in kernel 2.6.12.
225 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
226 .\" http://lkml.org/lkml/2005/7/1/165
228 POSIX.1-2001 says that
232 value is specified that is outside of the range 0 to 999999.
233 However, in kernels up to and including 2.6.21,
234 Linux does not give an error, but instead silently
235 adjusts the corresponding seconds value for the timer.
236 From kernel 2.6.22 onward,
237 this nonconformance has been repaired:
243 .\" Bugzilla report 25 Apr 2006:
244 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
245 .\" "setitimer() should reject noncanonical arguments"
247 .BR gettimeofday (2),
250 .BR timer_create (2),
251 .BR timerfd_create (2),