-
Notifications
You must be signed in to change notification settings - Fork 0
/
setitimer.html
358 lines (274 loc) · 10.9 KB
/
setitimer.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:48 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>GETITIMER</title>
</head>
<body>
<h1 align="center">GETITIMER</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">getitimer,
setitimer - get or set value of an interval timer</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/time.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
getitimer(int</b> <i>which</i><b>, struct itimerval
*</b><i>curr_value</i><b>); <br>
int setitimer(int</b> <i>which</i><b>, const struct
itimerval *</b><i>new_value</i><b>, <br>
struct itimerval *</b><i>old_value</i><b>);</b></p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">These system
calls provide access to interval timers, that is, timers
that initially expire at some point in the future, and
(optionally) at regular intervals after that. When a timer
expires, a signal is generated for the calling process, and
the timer is reset to the specified interval (if the
interval is nonzero).</p>
<p style="margin-left:11%; margin-top: 1em">Three types of
timers—specified via the <i>which</i>
argument—are provided, each of which counts against a
different clock and generates a different signal on timer
expiration:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="21%">
<p><b>ITIMER_REAL</b></p></td>
<td width="2%"></td>
<td width="66%">
<p>This timer counts down in real (i.e., wall clock) time.
At each expiration, a <b>SIGALRM</b> signal is
generated.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="21%">
<p><b>ITIMER_VIRTUAL</b></p></td>
<td width="2%"></td>
<td width="66%">
<p>This timer counts down against the user-mode CPU time
consumed by the process. (The measurement includes CPU time
consumed by all threads in the process.) At each expiration,
a <b>SIGVTALRM</b> signal is generated.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="21%">
<p><b>ITIMER_PROF</b></p></td>
<td width="2%"></td>
<td width="66%">
<p>This timer counts down against the total (i.e., both
user and system) CPU time consumed by the process. (The
measurement includes CPU time consumed by all threads in the
process.) At each expiration, a <b>SIGPROF</b> signal is
generated.</p> </td></tr>
</table>
<p style="margin-left:34%; margin-top: 1em">In conjunction
with <b>ITIMER_VIRTUAL</b>, this timer can be used to
profile user and system CPU time consumed by the
process.</p>
<p style="margin-left:11%; margin-top: 1em">A process has
only one of each of the three types of timers.</p>
<p style="margin-left:11%; margin-top: 1em">Timer values
are defined by the following structures:</p>
<p style="margin-left:17%; margin-top: 1em">struct
itimerval { <br>
struct timeval it_interval; /* Interval for periodic timer
*/ <br>
struct timeval it_value; /* Time until next expiration */
<br>
};</p>
<p style="margin-left:17%; margin-top: 1em">struct timeval
{ <br>
time_t tv_sec; /* seconds */ <br>
suseconds_t tv_usec; /* microseconds */ <br>
};</p>
<p style="margin-left:11%; margin-top: 1em"><b>getitimer()</b>
<br>
The function <b>getitimer</b>() places the current value of
the timer specified by <i>which</i> in the buffer pointed to
by <i>curr_value</i>.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>it_value</i> substructure is populated with the amount of
time remaining until the next expiration of the specified
timer. This value changes as the timer counts down, and will
be reset to <i>it_interval</i> when the timer expires. If
both fields of <i>it_value</i> are zero, then this timer is
currently disarmed (inactive).</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>it_interval</i> substructure is populated with the timer
interval. If both fields of <i>it_interval</i> are zero,
then this is a single-shot timer (i.e., it expires just
once).</p>
<p style="margin-left:11%; margin-top: 1em"><b>setitimer()</b>
<br>
The function <b>setitimer</b>() arms or disarms the timer
specified by <i>which</i>, by setting the timer to the value
specified by <i>new_value</i>. If <i>old_value</i> is
non-NULL, the buffer it points to is used to return the
previous value of the timer (i.e., the same information that
is returned by <b>getitimer</b>()).</p>
<p style="margin-left:11%; margin-top: 1em">If either field
in <i>new_value.it_value</i> is nonzero, then the timer is
armed to initially expire at the specified time. If both
fields in <i>new_value.it_value</i> are zero, then the timer
is disarmed.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>new_value.it_interval</i> field specifies the new
interval for the timer; if both of its subfields are zero,
the timer is single-shot.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success,
zero is returned. On error, -1 is returned, and <i>errno</i>
is set appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em"><i>new_value</i>,
<i>old_value</i>, or <i>curr_value</i> is not valid a
pointer.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>which</i> is not one of <b>ITIMER_REAL</b>,
<b>ITIMER_VIRTUAL</b>, or <b>ITIMER_PROF</b>; or (since
Linux 2.6.22) one of the <i>tv_usec</i> fields in the
structure pointed to by <i>new_value</i> contains a value
outside the range 0 to 999999.</p></td></tr>
</table>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">POSIX.1-2001,
SVr4, 4.4BSD (this call first appeared in 4.2BSD).
POSIX.1-2008 marks <b>getitimer</b>() and <b>setitimer</b>()
obsolete, recommending the use of the POSIX timers API
(<b>timer_gettime</b>(2), <b>timer_settime</b>(2), etc.)
instead.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Timers will
never expire before the requested time, but may expire some
(short) time afterward, which depends on the system timer
resolution and on the system load; see <b>time</b>(7). (But
see BUGS below.) If the timer expires while the process is
active (always true for <b>ITIMER_VIRTUAL</b>), the signal
will be delivered immediately when generated.</p>
<p style="margin-left:11%; margin-top: 1em">A child created
via <b>fork</b>(2) does not inherit its parent’s
interval timers. Interval timers are preserved across an
<b>execve</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">POSIX.1 leaves
the interaction between <b>setitimer</b>() and the three
interfaces <b>alarm</b>(2), <b>sleep</b>(3), and
<b>usleep</b>(3) unspecified.</p>
<p style="margin-left:11%; margin-top: 1em">The standards
are silent on the meaning of the call:</p>
<p style="margin-left:11%; margin-top: 1em">setitimer(which,
NULL, &old_value);</p>
<p style="margin-left:11%; margin-top: 1em">Many systems
(Solaris, the BSDs, and perhaps others) treat this as
equivalent to:</p>
<p style="margin-left:11%; margin-top: 1em">getitimer(which,
&old_value);</p>
<p style="margin-left:11%; margin-top: 1em">In Linux, this
is treated as being equivalent to a call in which the
<i>new_value</i> fields are zero; that is, the timer is
disabled. <i>Don’t use this Linux misfeature</i>: it
is nonportable and unnecessary.</p>
<h2>BUGS
<a name="BUGS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The generation
and delivery of a signal are distinct, and only one instance
of each of the signals listed above may be pending for a
process. Under very heavy loading, an <b>ITIMER_REAL</b>
timer may expire before the signal from a previous
expiration has been delivered. The second signal in such an
event will be lost.</p>
<p style="margin-left:11%; margin-top: 1em">On Linux
kernels before 2.6.16, timer values are represented in
jiffies. If a request is made set a timer with a value whose
jiffies representation exceeds <b>MAX_SEC_IN_JIFFIES</b>
(defined in <i>include/linux/jiffies.h</i>), then the timer
is silently truncated to this ceiling value. On Linux/i386
(where, since Linux 2.6.13, the default jiffy is 0.004
seconds), this means that the ceiling value for a timer is
approximately 99.42 days. Since Linux 2.6.16, the kernel
uses a different internal representation for times, and this
ceiling is removed.</p>
<p style="margin-left:11%; margin-top: 1em">On certain
systems (including i386), Linux kernels before version
2.6.12 have a bug which will produce premature timer
expirations of up to one jiffy under some circumstances.
This bug is fixed in kernel 2.6.12.</p>
<p style="margin-left:11%; margin-top: 1em">POSIX.1-2001
says that <b>setitimer</b>() should fail if a <i>tv_usec</i>
value is specified that is outside of the range 0 to 999999.
However, in kernels up to and including 2.6.21, Linux does
not give an error, but instead silently adjusts the
corresponding seconds value for the timer. From kernel
2.6.22 onward, this nonconformance has been repaired: an
improper <i>tv_usec</i> value results in an <b>EINVAL</b>
error.</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>gettimeofday</b>(2),
<b>sigaction</b>(2), <b>signal</b>(2),
<b>timer_create</b>(2), <b>timerfd_create</b>(2),
<b>time</b>(7)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>