1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public
15 .\" License along with this manual; if not, see
16 .\" <http://www.gnu.org/licenses/>.
19 .\" FIXME: Linux 3.0: timerfd_settime() adds a TFD_TIMER_CANCEL_ON_SET flag.
21 .TH TIMERFD_CREATE 2 2011-09-14 Linux "Linux Programmer's Manual"
23 timerfd_create, timerfd_settime, timerfd_gettime \-
24 timers that notify via file descriptors
27 .B #include <sys/timerfd.h>
29 .BI "int timerfd_create(int " clockid ", int " flags );
31 .BI "int timerfd_settime(int " fd ", int " flags ,
32 .BI " const struct itimerspec *" new_value ,
33 .BI " struct itimerspec *" old_value );
35 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
38 These system calls create and operate on a timer
39 that delivers timer expiration notifications via a file descriptor.
40 They provide an alternative to the use of
44 with the advantage that the file descriptor may be monitored by
50 The use of these three system calls is analogous to the use of
52 .BR timer_settime (2),
54 .BR timer_gettime (2).
55 (There is no analog of
56 .BR timer_getoverrun (2),
57 since that functionality is provided by
63 creates a new timer object,
64 and returns a file descriptor that refers to that timer.
67 argument specifies the clock that is used to mark the progress
68 of the timer, and must be either
73 is a settable system-wide clock.
75 is a nonsettable clock that is not affected
76 by discontinuous changes in the system clock
77 (e.g., manual changes to system time).
78 The current value of each of these clocks can be retrieved using
79 .BR clock_gettime (2).
81 Starting with Linux 2.6.27, the following values may be bitwise ORed in
83 to change the behavior of
84 .BR timerfd_create ():
89 file status flag on the new open file description.
90 Using this flag saves extra calls to
92 to achieve the same result.
97 flag on the new file descriptor.
98 See the description of the
102 for reasons why this may be useful.
104 In Linux versions up to and including 2.6.26,
106 must be specified as zero.
107 .SS timerfd_settime()
108 .BR timerfd_settime ()
109 arms (starts) or disarms (stops)
110 the timer referred to by the file descriptor
115 argument specifies the initial expiration and interval for the timer.
118 structure used for this argument contains two fields,
119 each of which is in turn a structure of type
125 time_t tv_sec; /* Seconds */
126 long tv_nsec; /* Nanoseconds */
130 struct timespec it_interval; /* Interval for periodic timer */
131 struct timespec it_value; /* Initial expiration */
136 .I new_value.it_value
137 specifies the initial expiration of the timer,
138 in seconds and nanoseconds.
139 Setting either field of
140 .I new_value.it_value
141 to a nonzero value arms the timer.
142 Setting both fields of
143 .I new_value.it_value
144 to zero disarms the timer.
146 Setting one or both fields of
147 .I new_value.it_interval
148 to nonzero values specifies the period, in seconds and nanoseconds,
149 for repeated timer expirations after the initial expiration.
151 .I new_value.it_interval
152 are zero, the timer expires just once, at the time specified by
153 .IR new_value.it_value .
157 argument is either 0, to start a relative timer
158 .RI ( new_value.it_value
159 specifies a time relative to the current value of the clock specified by
162 .BR TFD_TIMER_ABSTIME ,
163 to start an absolute timer
164 .RI ( new_value.it_value
165 specifies an absolute time for the clock specified by
167 that is, the timer will expire when the value of that
168 clock reaches the value specified in
169 .IR new_value.it_value ).
173 argument is not NULL, then the
175 structure that it points to is used to return the setting of the timer
176 that was current at the time of the call;
177 see the description of
178 .BR timerfd_gettime ()
181 .SS timerfd_gettime()
182 .BR timerfd_gettime ()
187 structure that contains the current setting of the timer
188 referred to by the file descriptor
193 field returns the amount of time
194 until the timer will next expire.
195 If both fields of this structure are zero,
196 then the timer is currently disarmed.
197 This field always contains a relative value, regardless of whether the
198 .BR TFD_TIMER_ABSTIME
199 flag was specified when setting the timer.
203 field returns the interval of the timer.
204 If both fields of this structure are zero,
205 then the timer is set to expire just once, at the time specified by
206 .IR curr_value.it_value .
207 .SS Operating on a timer file descriptor
208 The file descriptor returned by
209 .BR timerfd_create ()
210 supports the following operations:
213 If the timer has already expired one or more times since
214 its settings were last modified using
215 .BR timerfd_settime (),
216 or since the last successful
218 then the buffer given to
220 returns an unsigned 8-byte integer
222 containing the number of expirations that have occurred.
223 (The returned value is in host byte order\(emthat is,
224 the native byte order for integers on the host machine.)
226 If no timer expirations have occurred at the time of the
228 then the call either blocks until the next timer expiration,
229 or fails with the error
231 if the file descriptor has been made nonblocking
241 will fail with the error
243 if the size of the supplied buffer is less than 8 bytes.
245 .BR poll "(2), " select "(2) (and similar)"
246 The file descriptor is readable
254 if one or more timer expirations have occurred.
256 The file descriptor also supports the other file-descriptor
264 When the file descriptor is no longer required it should be closed.
265 When all file descriptors associated with the same timer object
267 the timer is disarmed and its resources are freed by the kernel.
269 .SS fork(2) semantics
272 the child inherits a copy of the file descriptor created by
273 .BR timerfd_create ().
274 The file descriptor refers to the same underlying
275 timer object as the corresponding file descriptor in the parent,
278 in the child will return information about
279 expirations of the timer.
281 .SS execve(2) semantics
282 A file descriptor created by
283 .BR timerfd_create ()
286 and continues to generate timer expirations if the timer was armed.
289 .BR timerfd_create ()
290 returns a new file descriptor.
291 On error, \-1 is returned and
293 is set to indicate the error.
295 .BR timerfd_settime ()
297 .BR timerfd_gettime ()
299 on error they return \-1, and set
301 to indicate the error.
303 .BR timerfd_create ()
304 can fail with the following errors:
317 or, in Linux 2.6.26 or earlier,
322 The per-process limit of open file descriptors has been reached.
325 The system-wide limit on the total number of open files has been
329 Could not mount (internal) anonymous inode device.
332 There was insufficient kernel memory to create the timer.
334 .BR timerfd_settime ()
336 .BR timerfd_gettime ()
337 can fail with the following errors:
341 is not a valid file descriptor.
348 is not valid a pointer.
352 is not a valid timerfd file descriptor.
354 .BR timerfd_settime ()
355 can also fail with the following errors:
359 is not properly initialized (one of the
361 falls outside the range zero to 999,999,999).
364 .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
365 .\" In older kernel versions, no check was made for invalid flags.
369 These system calls are available on Linux since kernel 2.6.25.
370 Library support is provided by glibc since version 2.8.
372 These system calls are Linux-specific.
376 .BR timerfd_create ()
377 supports fewer types of clock IDs than
378 .BR timer_create (2).
380 The following program creates a timer and then monitors its progress.
381 The program accepts up to three command-line arguments.
382 The first argument specifies the number of seconds for
383 the initial expiration of the timer.
384 The second argument specifies the interval for the timer, in seconds.
385 The third argument specifies the number of times the program should
386 allow the timer to expire before terminating.
387 The second and third command-line arguments are optional.
389 The following shell session demonstrates the use of the program:
393 .RB "$" " a.out 3 1 100"
395 3.000: read: 1; total=1
396 4.000: read: 1; total=2
397 .BR "^Z " " # type control-Z to suspend the program"
398 [1]+ Stopped ./timerfd3_demo 3 1 100
399 .RB "$ " "fg" " # Resume execution after a few seconds"
401 9.660: read: 5; total=7
402 10.000: read: 1; total=8
403 11.000: read: 1; total=9
404 .BR "^C " " # type control-C to suspend the program"
410 .\" The commented out code here is what we currently need until
411 .\" the required stuff is in glibc
414 .\"/* Link with -lrt */
415 .\"#define _GNU_SOURCE
416 .\"#include <sys/syscall.h>
417 .\"#include <unistd.h>
419 .\"#if defined(__i386__)
420 .\"#define __NR_timerfd_create 322
421 .\"#define __NR_timerfd_settime 325
422 .\"#define __NR_timerfd_gettime 326
426 .\"timerfd_create(int clockid, int flags)
428 .\" return syscall(__NR_timerfd_create, clockid, flags);
432 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
433 .\" struct itimerspec *curr_value)
435 .\" return syscall(__NR_timerfd_settime, fd, flags, new_value,
440 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
442 .\" return syscall(__NR_timerfd_gettime, fd, curr_value);
445 .\"#define TFD_TIMER_ABSTIME (1 << 0)
447 .\"////////////////////////////////////////////////////////////
448 #include <sys/timerfd.h>
453 #include <stdint.h> /* Definition of uint64_t */
455 #define handle_error(msg) \\
456 do { perror(msg); exit(EXIT_FAILURE); } while (0)
459 print_elapsed_time(void)
461 static struct timespec start;
462 struct timespec curr;
463 static int first_call = 1;
468 if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
469 handle_error("clock_gettime");
472 if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
473 handle_error("clock_gettime");
475 secs = curr.tv_sec \- start.tv_sec;
476 nsecs = curr.tv_nsec \- start.tv_nsec;
481 printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
485 main(int argc, char *argv[])
487 struct itimerspec new_value;
490 uint64_t exp, tot_exp;
493 if ((argc != 2) && (argc != 4)) {
494 fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n",
499 if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
500 handle_error("clock_gettime");
502 /* Create a CLOCK_REALTIME absolute timer with initial
503 expiration and interval as specified in command line */
505 new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
506 new_value.it_value.tv_nsec = now.tv_nsec;
508 new_value.it_interval.tv_sec = 0;
511 new_value.it_interval.tv_sec = atoi(argv[2]);
512 max_exp = atoi(argv[3]);
514 new_value.it_interval.tv_nsec = 0;
516 fd = timerfd_create(CLOCK_REALTIME, 0);
518 handle_error("timerfd_create");
520 if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
521 handle_error("timerfd_settime");
523 print_elapsed_time();
524 printf("timer started\\n");
526 for (tot_exp = 0; tot_exp < max_exp;) {
527 s = read(fd, &exp, sizeof(uint64_t));
528 if (s != sizeof(uint64_t))
529 handle_error("read");
532 print_elapsed_time();
533 printf("read: %llu; total=%llu\\n",
534 (unsigned long long) exp,
535 (unsigned long long) tot_exp);
548 .BR timer_create (2),
549 .BR timer_gettime (2),
550 .BR timer_settime (2),
554 This page is part of release 3.68 of the Linux
557 A description of the project,
558 information about reporting bugs,
559 and the latest version of this page,
561 \%http://www.kernel.org/doc/man\-pages/.