Debian Codegraph @

upstream/debian-unstable/man2/getitimer.2

raw
1 .\" Copyright 1993, Darren Senn <[email protected]>
2 .\" Copyright 2016, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
6 .\" May be freely distributed and modified
7 .\" %%%LICENSE_END
8 .\"
9 .TH getitimer 2 2026-02-08 "Linux man-pages 6.18"
10 .SH NAME
11 getitimer, setitimer \- get or set value of an interval timer
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <sys/time.h>
18 .P
19 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
20 .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
21 .BI " struct itimerval *_Nullable restrict " old_value );
22 .fi
23 .SH DESCRIPTION
24 These system calls provide access to interval timers, that is,
25 timers that initially expire at some point in the future,
26 and (optionally) at regular intervals after that.
27 When a timer expires, a signal is generated for the calling process,
28 and the timer is reset to the specified interval
29 (if the interval is nonzero).
30 .P
31 Three types of timers\[em]specified via the
32 .I which
33 argument\[em]are provided,
34 each of which counts against a different clock and
35 generates a different signal on timer expiration:
36 .TP
37 .B ITIMER_REAL
38 This timer counts down in real (i.e., wall clock) time.
39 At each expiration, a
40 .B SIGALRM
41 signal is generated.
42 .TP
43 .B ITIMER_VIRTUAL
44 This timer counts down against the user-mode CPU time consumed by the process.
45 (The measurement includes CPU time consumed by all threads in the process.)
46 At each expiration, a
47 .B SIGVTALRM
48 signal is generated.
49 .TP
50 .B ITIMER_PROF
51 This timer counts down against the total (i.e., both user and system)
52 CPU time consumed by the process.
53 (The measurement includes CPU time consumed by all threads in the process.)
54 At each expiration, a
55 .B SIGPROF
56 signal is generated.
57 .IP
58 In conjunction with
59 .BR ITIMER_VIRTUAL ,
60 this timer can be used to profile user and system CPU time
61 consumed by the process.
62 .P
63 A process has only one of each of the three types of timers.
64 .P
65 Timer values are defined by the following structures:
66 .P
67 .in +4n
68 .EX
69 struct itimerval {
70 struct timeval it_interval; /* Interval for periodic timer */
71 struct timeval it_value; /* Time until next expiration */
72 };
73 \&
74 struct timeval {
75 time_t tv_sec; /* seconds */
76 suseconds_t tv_usec; /* microseconds */
77 };
78 .EE
79 .in
80 .\"
81 .SS getitimer()
82 The function
83 .BR getitimer ()
84 places the current value of the timer specified by
85 .I which
86 in the buffer pointed to by
87 .IR curr_value .
88 .P
89 The
90 .I it_value
91 substructure is populated with the amount of time remaining until
92 the next expiration of the specified timer.
93 This value changes as the timer counts down, and will be reset to
94 .I it_interval
95 when the timer expires.
96 If both fields of
97 .I it_value
98 are zero, then this timer is currently disarmed (inactive).
99 .P
100 The
101 .I it_interval
102 substructure is populated with the timer interval.
103 If both fields of
104 .I it_interval
105 are zero, then this is a single-shot timer (i.e., it expires just once).
106 .SS setitimer()
107 The function
108 .BR setitimer ()
109 arms or disarms the timer specified by
110 .IR which ,
111 by setting the timer to the value specified by
112 .IR new_value .
113 If
114 .I old_value
115 is non-NULL,
116 the buffer it points to is used to return the previous value of the timer
117 (i.e., the same information that is returned by
118 .BR getitimer ()).
119 .P
120 If either field in
121 .I new_value.it_value
122 is nonzero,
123 then the timer is armed to initially expire at the specified time.
124 If both fields in
125 .I new_value.it_value
126 are zero, then the timer is disarmed.
127 .P
128 The
129 .I new_value.it_interval
130 field specifies the new interval for the timer;
131 if both of its subfields are zero, the timer is single-shot.
132 .SH RETURN VALUE
133 On success, zero is returned.
134 On error, \-1 is returned, and
135 .I errno
136 is set to indicate the error.
137 .SH ERRORS
138 .TP
139 .B EFAULT
140 .IR new_value ,
141 .IR old_value ,
142 or
143 .I curr_value
144 is not a valid pointer.
145 .TP
146 .B EINVAL
147 .I which
148 is not one of
149 .BR ITIMER_REAL ,
150 .BR ITIMER_VIRTUAL ,
151 or
152 .BR ITIMER_PROF ;
153 or (since Linux 2.6.22) one of the
154 .I tv_usec
155 fields in the structure pointed to by
156 .I new_value
157 contains a value outside the range [0, 999999].
158 .SH VERSIONS
159 The standards are silent on the meaning of the call:
160 .P
161 .in +4n
162 .EX
163 setitimer(which, NULL, &old_value);
164 .EE
165 .in
166 .P
167 Many systems (Solaris, the BSDs, and perhaps others)
168 treat this as equivalent to:
169 .P
170 .in +4n
171 .EX
172 getitimer(which, &old_value);
173 .EE
174 .in
175 .P
176 In Linux, this is treated as being equivalent to a call in which the
177 .I new_value
178 fields are zero;
179 that is,
180 the timer is disabled.
181 .IR "Don't use this Linux misfeature" :
182 it is nonportable and unnecessary.
183 .SH STANDARDS
184 None.
185 .SH HISTORY
186 4.2BSD,
187 SVr4,
188 SUSv1,
189 POSIX.1-2001.
190 POSIX.1-2008 marked
191 .BR getitimer ()
192 and
193 .BR setitimer ()
194 obsolete, recommending the use of the POSIX timers API
195 .RB ( timer_gettime (2),
196 .BR timer_settime (2),
197 etc.) instead.
198 POSIX.1-2024 removed them.
199 .SH NOTES
200 Timers will never expire before the requested time,
201 but may expire some (short) time afterward, which depends
202 on the system timer resolution and on the system load;
203 see
204 .BR time (7).
205 (But see BUGS below.)
206 If the timer expires while the process is active (always true for
207 .BR ITIMER_VIRTUAL ),
208 the signal will be delivered immediately when generated.
209 .P
210 A child created via
211 .BR fork (2)
212 does not inherit its parent's interval timers.
213 Interval timers are preserved across an
214 .BR execve (2).
215 .P
216 POSIX.1 leaves the
217 interaction between
218 .BR setitimer ()
219 and the three interfaces
220 .BR alarm (2),
221 .BR sleep (3),
222 and
223 .BR usleep (3)
224 unspecified.
225 .SH BUGS
226 The generation and delivery of a signal are distinct, and
227 only one instance of each of the signals listed above may be pending
228 for a process.
229 Under very heavy loading, an
230 .B ITIMER_REAL
231 timer may expire before the signal from a previous expiration
232 has been delivered.
233 The second signal in such an event will be lost.
234 .P
235 Before Linux 2.6.16, timer values are represented in jiffies.
236 If a request is made set a timer with a value whose jiffies
237 representation exceeds
238 .B MAX_SEC_IN_JIFFIES
239 (defined in
240 .IR include/linux/jiffies.h ),
241 then the timer is silently truncated to this ceiling value.
242 On Linux/i386 (where, since Linux 2.6.13,
243 the default jiffy is 0.004 seconds),
244 this means that the ceiling value for a timer is
245 approximately 99.42 days.
246 Since Linux 2.6.16,
247 the kernel uses a different internal representation for times,
248 and this ceiling is removed.
249 .P
250 On certain systems (including i386),
251 Linux kernels before Linux 2.6.12 have a bug which will produce
252 premature timer expirations of up to one jiffy under some circumstances.
253 This bug is fixed in Linux 2.6.12.
254 .\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x.
255 .\" http://lkml.org/lkml/2005/7/1/165
256 .P
257 POSIX.1-2001 says that
258 .BR setitimer ()
259 should fail if a
260 .I tv_usec
261 value is specified that is outside of the range [0, 999999].
262 However, up to and including Linux 2.6.21,
263 Linux does not give an error, but instead silently
264 adjusts the corresponding seconds value for the timer.
265 From Linux 2.6.22 onward,
266 this nonconformance has been repaired:
267 an improper
268 .I tv_usec
269 value results in an
270 .B EINVAL
271 error.
272 .\" Bugzilla report 25 Apr 2006:
273 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
274 .\" "setitimer() should reject noncanonical arguments"
275 .SH SEE ALSO
276 .BR gettimeofday (2),
277 .BR sigaction (2),
278 .BR signal (2),
279 .BR timer_create (2),
280 .BR timerfd_create (2),
281 .BR time (7)