]>
Commit | Line | Data |
---|---|---|
45b81c9c MK |
1 | .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" This program is free software; you can redistribute it and/or modify | |
4 | .\" it under the terms of the GNU General Public License as published by | |
5 | .\" the Free Software Foundation; either version 2 of the License, or | |
6 | .\" (at your option) any later version. | |
7 | .\" | |
8 | .\" This program is distributed in the hope that it will be useful, | |
9 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
10 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
11 | .\" GNU General Public License for more details. | |
12 | .\" | |
13 | .\" You should have received a copy of the GNU General Public License | |
14 | .\" along with this program; if not, write to the Free Software | |
15 | .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
16 | .\" MA 02111-1307 USA | |
17 | .\" | |
86d95cf2 | 18 | .TH TIMERFD_CREATE 2 2009-03-10 Linux "Linux Programmer's Manual" |
45b81c9c MK |
19 | .SH NAME |
20 | timerfd_create, timerfd_settime, timerfd_gettime \- | |
21 | timers that notify via file descriptors | |
22 | .SH SYNOPSIS | |
45b81c9c MK |
23 | .nf |
24 | .B #include <sys/timerfd.h> | |
25 | .sp | |
26 | .BI "int timerfd_create(int " clockid ", int " flags ); | |
27 | .sp | |
28 | .BI "int timerfd_settime(int " fd ", int " flags , | |
29 | .BI " const struct itimerspec *" new_value , | |
5c902597 | 30 | .BI " struct itimerspec *" old_value ); |
45b81c9c MK |
31 | .sp |
32 | .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value ); | |
33 | .fi | |
34 | .SH DESCRIPTION | |
35 | These system calls create and operate on a timer | |
36 | that delivers timer expiration notifications via a file descriptor. | |
37 | They provide an alternative to the use of | |
38 | .BR setitimer (2) | |
39 | or | |
804f03e6 | 40 | .BR timer_create (2), |
45b81c9c MK |
41 | with the advantage that the file descriptor may be monitored by |
42 | .BR select (2), | |
43 | .BR poll (2), | |
44 | and | |
45 | .BR epoll (7). | |
46 | ||
47 | The use of these three system calls is analogous to the use of | |
804f03e6 MK |
48 | .BR timer_create (2), |
49 | .BR timer_settime (2), | |
45b81c9c | 50 | and |
804f03e6 | 51 | .BR timer_gettime (2). |
45b81c9c | 52 | (There is no analog of |
804f03e6 | 53 | .BR timer_getoverrun (2), |
45b81c9c MK |
54 | since that functionality is provided by |
55 | .BR read (2), | |
56 | as described below.) | |
57 | .\" | |
58 | .SS timerfd_create() | |
59 | .BR timerfd_create () | |
60 | creates a new timer object, | |
61 | and returns a file descriptor that refers to that timer. | |
62 | The | |
63 | .I clockid | |
64 | argument specifies the clock that is used to mark the progress | |
65 | of the timer, and must be either | |
66 | .B CLOCK_REALTIME | |
67 | or | |
68 | .BR CLOCK_MONOTONIC . | |
69 | .B CLOCK_REALTIME | |
70 | is a settable system-wide clock. | |
71 | .B CLOCK_MONOTONIC | |
72 | is a non-settable clock that is not affected | |
73 | by discontinuous changes in the system clock | |
74 | (e.g., manual changes to system time). | |
75 | The current value of each of these clocks can be retrieved using | |
0eb44391 | 76 | .BR clock_gettime (2). |
45b81c9c | 77 | |
3df1b973 MK |
78 | Starting with Linux 2.6.27, the following values may be bitwise ORed in |
79 | .IR flags | |
80 | to change the behavior of | |
81 | .BR timerfd_create (): | |
82 | .TP 14 | |
83 | .B TFD_NONBLOCK | |
84 | Set the | |
85 | .BR O_NONBLOCK | |
b25c5b23 | 86 | file status flag on the new open file description. |
3df1b973 | 87 | Using this flag saves extra calls to |
ef7db4f5 | 88 | .BR fcntl (2) |
3df1b973 MK |
89 | to achieve the same result. |
90 | .TP | |
91 | .B TFD_CLOEXEC | |
92 | Set the close-on-exec | |
93 | .RB ( FD_CLOEXEC ) | |
94 | flag on the new file descriptor. | |
c5571b61 | 95 | See the description of the |
3df1b973 MK |
96 | .B O_CLOEXEC |
97 | flag in | |
98 | .BR open (2) | |
99 | for reasons why this may be useful. | |
100 | .PP | |
101 | In Linux versions up to and including 2.6.26, | |
45b81c9c | 102 | .I flags |
3df1b973 | 103 | must be specified as zero. |
45b81c9c MK |
104 | .SS timerfd_settime() |
105 | .BR timerfd_settime () | |
106 | arms (starts) or disarms (stops) | |
107 | the timer referred to by the file descriptor | |
108 | .IR fd . | |
109 | ||
110 | The | |
111 | .I new_value | |
112 | argument specifies the initial expiration and interval for the timer. | |
113 | The | |
114 | .I itimer | |
115 | structure used for this argument contains two fields, | |
116 | each of which is in turn a structure of type | |
117 | .IR timespec : | |
118 | .in +4n | |
119 | .nf | |
120 | ||
121 | struct timespec { | |
122 | time_t tv_sec; /* Seconds */ | |
123 | long tv_nsec; /* Nanoseconds */ | |
124 | }; | |
125 | ||
126 | struct itimerspec { | |
127 | struct timespec it_interval; /* Interval for periodic timer */ | |
128 | struct timespec it_value; /* Initial expiration */ | |
129 | }; | |
130 | .fi | |
131 | .in | |
132 | .PP | |
133 | .I new_value.it_value | |
134 | specifies the initial expiration of the timer, | |
135 | in seconds and nanoseconds. | |
136 | Setting either field of | |
137 | .I new_value.it_value | |
c7094399 | 138 | to a nonzero value arms the timer. |
45b81c9c MK |
139 | Setting both fields of |
140 | .I new_value.it_value | |
141 | to zero disarms the timer. | |
142 | ||
143 | Setting one or both fields of | |
144 | .I new_value.it_interval | |
c7094399 | 145 | to nonzero values specifies the period, in seconds and nanoseconds, |
45b81c9c MK |
146 | for repeated timer expirations after the initial expiration. |
147 | If both fields of | |
148 | .I new_value.it_interval | |
149 | are zero, the timer expires just once, at the time specified by | |
150 | .IR new_value.it_value . | |
151 | ||
152 | The | |
153 | .I flags | |
154 | argument is either 0, to start a relative timer | |
155 | .RI ( new_value.it_interval | |
156 | specifies a time relative to the current value of the clock specified by | |
157 | .IR clockid ), | |
158 | or | |
159 | .BR TFD_TIMER_ABSTIME , | |
160 | to start an absolute timer | |
c3afed74 | 161 | .RI ( new_value.it_value |
45b81c9c MK |
162 | specifies an absolute time for the clock specified by |
163 | .IR clockid ; | |
164 | that is, the timer will expire when the value of that | |
165 | clock reaches the value specified in | |
33fb70ba | 166 | .IR new_value.it_value ). |
45b81c9c MK |
167 | |
168 | The | |
5c902597 | 169 | .I old_value |
45b81c9c MK |
170 | argument returns a structure containing the setting of the timer that |
171 | was current at the time of the call; see the description of | |
172 | .BR timerfd_gettime () | |
173 | following. | |
174 | .\" | |
175 | .SS timerfd_gettime() | |
176 | .BR timerfd_gettime () | |
177 | returns, in | |
178 | .IR curr_value , | |
179 | an | |
180 | .IR itimerspec | |
dc55661b | 181 | structure that contains the current setting of the timer |
45b81c9c MK |
182 | referred to by the file descriptor |
183 | .IR fd . | |
184 | ||
185 | The | |
186 | .I it_value | |
187 | field returns the amount of time | |
188 | until the timer will next expire. | |
189 | If both fields of this structure are zero, | |
190 | then the timer is currently disarmed. | |
191 | This field always contains a relative value, regardless of whether the | |
192 | .BR TFD_TIMER_ABSTIME | |
193 | flag was specified when setting the timer. | |
194 | ||
195 | The | |
196 | .I it_interval | |
197 | field returns the interval of the timer. | |
198 | If both fields of this structure are zero, | |
199 | then the timer is set to expire just once, at the time specified by | |
200 | .IR curr_value.it_value . | |
201 | .SS Operating on a timer file descriptor | |
202 | The file descriptor returned by | |
203 | .BR timerfd_create () | |
204 | supports the following operations: | |
205 | .TP | |
206 | .BR read (2) | |
207 | If the timer has already expired one or more times since | |
208 | its settings were last modified using | |
209 | .BR timerfd_settime (), | |
210 | or since the last successful | |
211 | .BR read (2), | |
212 | then the buffer given to | |
213 | .BR read (2) | |
214 | returns an unsigned 8-byte integer | |
215 | .RI ( uint64_t ) | |
216 | containing the number of expirations that have occurred. | |
217 | (The returned value is in host byte order, | |
218 | i.e., the native byte order for integers on the host machine.) | |
219 | .IP | |
220 | If no timer expirations have occurred at the time of the | |
221 | .BR read (2), | |
222 | then the call either blocks until the next timer expiration, | |
223 | or fails with the error | |
224 | .B EAGAIN | |
ff40dbb3 | 225 | if the file descriptor has been made nonblocking |
45b81c9c MK |
226 | (via the use of the |
227 | .BR fcntl (2) | |
228 | .B F_SETFL | |
229 | operation to set the | |
230 | .B O_NONBLOCK | |
231 | flag). | |
232 | .IP | |
233 | A | |
234 | .BR read (2) | |
235 | will fail with the error | |
236 | .B EINVAL | |
237 | if the size of the supplied buffer is less than 8 bytes. | |
238 | .TP | |
239 | .BR poll "(2), " select "(2) (and similar)" | |
240 | The file descriptor is readable | |
241 | (the | |
242 | .BR select (2) | |
243 | .I readfds | |
244 | argument; the | |
245 | .BR poll (2) | |
246 | .B POLLIN | |
247 | flag) | |
248 | if one or more timer expirations have occurred. | |
249 | .IP | |
250 | The file descriptor also supports the other file-descriptor | |
251 | multiplexing APIs: | |
252 | .BR pselect (2), | |
253 | .BR ppoll (2), | |
254 | and | |
255 | .BR epoll (7). | |
256 | .TP | |
257 | .BR close (2) | |
258 | When the file descriptor is no longer required it should be closed. | |
259 | When all file descriptors associated with the same timer object | |
260 | have been closed, | |
261 | the timer is disarmed and its resources are freed by the kernel. | |
262 | .\" | |
263 | .SS fork(2) semantics | |
264 | After a | |
265 | .BR fork (2), | |
266 | the child inherits a copy of the file descriptor created by | |
267 | .BR timerfd_create (). | |
268 | The file descriptor refers to the same underlying | |
269 | timer object as the corresponding file descriptor in the parent, | |
270 | and | |
271 | .BR read (2)s | |
272 | in the child will return information about | |
273 | expirations of the timer. | |
274 | .\" | |
275 | .SS execve(2) semantics | |
276 | A file descriptor created by | |
277 | .BR timerfd_create () | |
278 | is preserved across | |
279 | .BR execve (2), | |
280 | and continues to generate timer expirations if the timer was armed. | |
281 | .SH "RETURN VALUE" | |
282 | On success, | |
283 | .BR timerfd_create () | |
284 | returns a new file descriptor. | |
285 | On error, \-1 is returned and | |
286 | .I errno | |
287 | is set to indicate the error. | |
288 | ||
289 | .BR timerfd_settime () | |
290 | and | |
291 | .BR timerfd_gettime () | |
292 | return 0 on success; | |
293 | on error they return \-1, and set | |
294 | .I errno | |
295 | to indicate the error. | |
296 | .SH ERRORS | |
297 | .BR timerfd_create () | |
298 | can fail with the following errors: | |
299 | .TP | |
300 | .B EINVAL | |
301 | The | |
302 | .I clockid | |
303 | argument is neither | |
304 | .B CLOCK_MONOTONIC | |
305 | nor | |
306 | .BR CLOCK_REALTIME ; | |
3df1b973 MK |
307 | .TP |
308 | .B EINVAL | |
309 | .I flags | |
310 | is invalid; | |
311 | or, in Linux 2.6.26 or earlier, | |
45b81c9c | 312 | .I flags |
c7094399 | 313 | is nonzero. |
45b81c9c MK |
314 | .TP |
315 | .B EMFILE | |
316 | The per-process limit of open file descriptors has been reached. | |
317 | .TP | |
318 | .B ENFILE | |
319 | The system-wide limit on the total number of open files has been | |
320 | reached. | |
321 | .TP | |
322 | .B ENODEV | |
323 | Could not mount (internal) anonymous inode device. | |
324 | .TP | |
325 | .B ENOMEM | |
326 | There was insufficient kernel memory to create the timer. | |
327 | .PP | |
328 | .BR timerfd_settime () | |
329 | and | |
330 | .BR timerfd_gettime () | |
331 | can fail with the following errors: | |
332 | .TP | |
333 | .B EBADF | |
334 | .I fd | |
335 | is not a valid file descriptor. | |
336 | .TP | |
2bbb3907 MK |
337 | .B EFAULT |
338 | .IR new_value , | |
339 | .IR old_value , | |
340 | or | |
341 | .I curr_value | |
342 | is not valid a pointer. | |
343 | .TP | |
45b81c9c MK |
344 | .B EINVAL |
345 | .I fd | |
346 | is not a valid timerfd file descriptor. | |
c71b054d MK |
347 | .PP |
348 | .BR timerfd_settime () | |
349 | can also fail with the following errors: | |
350 | .TP | |
351 | .B EINVAL | |
45b81c9c MK |
352 | .I new_value |
353 | is not properly initialized (one of the | |
354 | .I tv_nsec | |
355 | falls outside the range zero to 999,999,999). | |
86d95cf2 MK |
356 | .TP |
357 | .B EINVAL | |
358 | .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version. | |
359 | .\" In older kernel versions, no check was made for invalid flags. | |
360 | .I flags | |
361 | is invalid. | |
45b81c9c MK |
362 | .SH VERSIONS |
363 | These system calls are available on Linux since kernel 2.6.25. | |
d6a54d42 | 364 | Library support is provided by glibc since version 2.8. |
45b81c9c MK |
365 | .SH CONFORMING TO |
366 | These system calls are Linux-specific. | |
367 | .SH EXAMPLE | |
368 | The following program creates a timer and then monitors its progress. | |
369 | The program accepts up to three command-line arguments. | |
370 | The first argument specifies the number of seconds for | |
371 | the initial expiration of the timer. | |
372 | The second argument specifies the interval for the timer, in seconds. | |
373 | The third argument specifies the number of times the program should | |
374 | allow the timer to expire before terminating. | |
375 | The second and third command-line arguments are optional. | |
376 | ||
377 | The following shell session demonstrates the use of the program: | |
378 | .in +4n | |
379 | .nf | |
380 | ||
b43a3b30 | 381 | .RB "$" " a.out 3 1 100" |
45b81c9c MK |
382 | 0.000: timer started |
383 | 3.000: read: 1; total=1 | |
384 | 4.000: read: 1; total=2 | |
b43a3b30 | 385 | .BR "^Z " " # type control-Z to suspend the program" |
45b81c9c | 386 | [1]+ Stopped ./timerfd3_demo 3 1 100 |
b43a3b30 | 387 | .RB "$ " "fg" " # Resume execution after a few seconds" |
45b81c9c MK |
388 | a.out 3 1 100 |
389 | 9.660: read: 5; total=7 | |
390 | 10.000: read: 1; total=8 | |
391 | 11.000: read: 1; total=9 | |
b43a3b30 | 392 | .BR "^C " " # type control-C to suspend the program" |
45b81c9c MK |
393 | .fi |
394 | .in | |
9c330504 | 395 | .SS Program source |
d84d0300 | 396 | \& |
45b81c9c | 397 | .nf |
45b81c9c MK |
398 | .\" The commented out code here is what we currently need until |
399 | .\" the required stuff is in glibc | |
400 | .\" | |
401 | .\" | |
402 | .\"/* Link with -lrt */ | |
403 | .\"#define _GNU_SOURCE | |
404 | .\"#include <sys/syscall.h> | |
405 | .\"#include <unistd.h> | |
406 | .\"#include <time.h> | |
407 | .\"#if defined(__i386__) | |
408 | .\"#define __NR_timerfd_create 322 | |
409 | .\"#define __NR_timerfd_settime 325 | |
410 | .\"#define __NR_timerfd_gettime 326 | |
411 | .\"#endif | |
412 | .\" | |
413 | .\"static int | |
414 | .\"timerfd_create(int clockid, int flags) | |
415 | .\"{ | |
416 | .\" return syscall(__NR_timerfd_create, clockid, flags); | |
417 | .\"} | |
418 | .\" | |
419 | .\"static int | |
420 | .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value, | |
421 | .\" struct itimerspec *curr_value) | |
422 | .\"{ | |
423 | .\" return syscall(__NR_timerfd_settime, fd, flags, new_value, | |
424 | .\" curr_value); | |
425 | .\"} | |
426 | .\" | |
427 | .\"static int | |
428 | .\"timerfd_gettime(int fd, struct itimerspec *curr_value) | |
429 | .\"{ | |
430 | .\" return syscall(__NR_timerfd_gettime, fd, curr_value); | |
431 | .\"} | |
432 | .\" | |
433 | .\"#define TFD_TIMER_ABSTIME (1 << 0) | |
434 | .\" | |
435 | .\"//////////////////////////////////////////////////////////// | |
45b81c9c MK |
436 | #include <sys/timerfd.h> |
437 | #include <time.h> | |
438 | #include <unistd.h> | |
439 | #include <stdlib.h> | |
440 | #include <stdio.h> | |
441 | #include <stdint.h> /* Definition of uint64_t */ | |
442 | ||
443 | #define handle_error(msg) \\ | |
444 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
445 | ||
446 | static void | |
447 | print_elapsed_time(void) | |
448 | { | |
449 | static struct timespec start; | |
450 | struct timespec curr; | |
451 | static int first_call = 1; | |
452 | int secs, nsecs; | |
453 | ||
454 | if (first_call) { | |
455 | first_call = 0; | |
456 | if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1) | |
457 | handle_error("clock_gettime"); | |
458 | } | |
459 | ||
460 | if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1) | |
461 | handle_error("clock_gettime"); | |
462 | ||
463 | secs = curr.tv_sec \- start.tv_sec; | |
464 | nsecs = curr.tv_nsec \- start.tv_nsec; | |
465 | if (nsecs < 0) { | |
466 | secs\-\-; | |
467 | nsecs += 1000000000; | |
468 | } | |
469 | printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000); | |
470 | } | |
471 | ||
472 | int | |
473 | main(int argc, char *argv[]) | |
474 | { | |
475 | struct itimerspec new_value; | |
476 | int max_exp, fd; | |
477 | struct timespec now; | |
478 | uint64_t exp, tot_exp; | |
479 | ssize_t s; | |
480 | ||
481 | if ((argc != 2) && (argc != 4)) { | |
482 | fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n", | |
483 | argv[0]); | |
484 | exit(EXIT_FAILURE); | |
485 | } | |
486 | ||
487 | if (clock_gettime(CLOCK_REALTIME, &now) == \-1) | |
488 | handle_error("clock_gettime"); | |
489 | ||
490 | /* Create a CLOCK_REALTIME absolute timer with initial | |
491 | expiration and interval as specified in command line */ | |
492 | ||
493 | new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]); | |
494 | new_value.it_value.tv_nsec = now.tv_nsec; | |
495 | if (argc == 2) { | |
496 | new_value.it_interval.tv_sec = 0; | |
497 | max_exp = 1; | |
498 | } else { | |
499 | new_value.it_interval.tv_sec = atoi(argv[2]); | |
500 | max_exp = atoi(argv[3]); | |
501 | } | |
502 | new_value.it_interval.tv_nsec = 0; | |
503 | ||
504 | fd = timerfd_create(CLOCK_REALTIME, 0); | |
505 | if (fd == \-1) | |
506 | handle_error("timerfd_create"); | |
507 | ||
a279595b | 508 | if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1) |
45b81c9c MK |
509 | handle_error("timerfd_settime"); |
510 | ||
511 | print_elapsed_time(); | |
512 | printf("timer started\\n"); | |
513 | ||
514 | for (tot_exp = 0; tot_exp < max_exp;) { | |
515 | s = read(fd, &exp, sizeof(uint64_t)); | |
516 | if (s != sizeof(uint64_t)) | |
517 | handle_error("read"); | |
518 | ||
519 | tot_exp += exp; | |
520 | print_elapsed_time(); | |
521 | printf("read: %llu; total=%llu\\n", | |
522 | (unsigned long long) exp, | |
523 | (unsigned long long) tot_exp); | |
524 | } | |
525 | ||
526 | exit(EXIT_SUCCESS); | |
527 | } | |
528 | .fi | |
6f8303a9 MK |
529 | .SH BUGS |
530 | Currently, | |
531 | .\" 2.6.29 | |
532 | .BR timerfd_create () | |
533 | supports fewer types of clock IDs than | |
534 | .BR timer_create (2). | |
45b81c9c MK |
535 | .SH "SEE ALSO" |
536 | .BR eventfd (2), | |
537 | .BR poll (2), | |
538 | .BR read (2), | |
539 | .BR select (2), | |
540 | .BR setitimer (2), | |
541 | .BR signalfd (2), | |
804f03e6 MK |
542 | .BR timer_create (2), |
543 | .BR timer_gettime (2), | |
544 | .BR timer_settime (2), | |
45b81c9c MK |
545 | .BR epoll (7), |
546 | .BR time (7) |