1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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,
18 .\" FIXME: Linux 3.0: timerfd_settime() adds a TFD_TIMER_CANCEL_ON_SET flag.
20 .TH TIMERFD_CREATE 2 2011-09-14 Linux "Linux Programmer's Manual"
22 timerfd_create, timerfd_settime, timerfd_gettime \-
23 timers that notify via file descriptors
26 .B #include <sys/timerfd.h>
28 .BI "int timerfd_create(int " clockid ", int " flags );
30 .BI "int timerfd_settime(int " fd ", int " flags ,
31 .BI " const struct itimerspec *" new_value ,
32 .BI " struct itimerspec *" old_value );
34 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
37 These system calls create and operate on a timer
38 that delivers timer expiration notifications via a file descriptor.
39 They provide an alternative to the use of
43 with the advantage that the file descriptor may be monitored by
49 The use of these three system calls is analogous to the use of
51 .BR timer_settime (2),
53 .BR timer_gettime (2).
54 (There is no analog of
55 .BR timer_getoverrun (2),
56 since that functionality is provided by
62 creates a new timer object,
63 and returns a file descriptor that refers to that timer.
66 argument specifies the clock that is used to mark the progress
67 of the timer, and must be either
72 is a settable system-wide clock.
74 is a nonsettable clock that is not affected
75 by discontinuous changes in the system clock
76 (e.g., manual changes to system time).
77 The current value of each of these clocks can be retrieved using
78 .BR clock_gettime (2).
80 Starting with Linux 2.6.27, the following values may be bitwise ORed in
82 to change the behavior of
83 .BR timerfd_create ():
88 file status flag on the new open file description.
89 Using this flag saves extra calls to
91 to achieve the same result.
96 flag on the new file descriptor.
97 See the description of the
101 for reasons why this may be useful.
103 In Linux versions up to and including 2.6.26,
105 must be specified as zero.
106 .SS timerfd_settime()
107 .BR timerfd_settime ()
108 arms (starts) or disarms (stops)
109 the timer referred to by the file descriptor
114 argument specifies the initial expiration and interval for the timer.
117 structure used for this argument contains two fields,
118 each of which is in turn a structure of type
124 time_t tv_sec; /* Seconds */
125 long tv_nsec; /* Nanoseconds */
129 struct timespec it_interval; /* Interval for periodic timer */
130 struct timespec it_value; /* Initial expiration */
135 .I new_value.it_value
136 specifies the initial expiration of the timer,
137 in seconds and nanoseconds.
138 Setting either field of
139 .I new_value.it_value
140 to a nonzero value arms the timer.
141 Setting both fields of
142 .I new_value.it_value
143 to zero disarms the timer.
145 Setting one or both fields of
146 .I new_value.it_interval
147 to nonzero values specifies the period, in seconds and nanoseconds,
148 for repeated timer expirations after the initial expiration.
150 .I new_value.it_interval
151 are zero, the timer expires just once, at the time specified by
152 .IR new_value.it_value .
156 argument is either 0, to start a relative timer
157 .RI ( new_value.it_value
158 specifies a time relative to the current value of the clock specified by
161 .BR TFD_TIMER_ABSTIME ,
162 to start an absolute timer
163 .RI ( new_value.it_value
164 specifies an absolute time for the clock specified by
166 that is, the timer will expire when the value of that
167 clock reaches the value specified in
168 .IR new_value.it_value ).
172 argument is not NULL, then the
174 structure that it points to is used to return the setting of the timer
175 that was current at the time of the call;
176 see the description of
177 .BR timerfd_gettime ()
180 .SS timerfd_gettime()
181 .BR timerfd_gettime ()
186 structure that contains the current setting of the timer
187 referred to by the file descriptor
192 field returns the amount of time
193 until the timer will next expire.
194 If both fields of this structure are zero,
195 then the timer is currently disarmed.
196 This field always contains a relative value, regardless of whether the
197 .BR TFD_TIMER_ABSTIME
198 flag was specified when setting the timer.
202 field returns the interval of the timer.
203 If both fields of this structure are zero,
204 then the timer is set to expire just once, at the time specified by
205 .IR curr_value.it_value .
206 .SS Operating on a timer file descriptor
207 The file descriptor returned by
208 .BR timerfd_create ()
209 supports the following operations:
212 If the timer has already expired one or more times since
213 its settings were last modified using
214 .BR timerfd_settime (),
215 or since the last successful
217 then the buffer given to
219 returns an unsigned 8-byte integer
221 containing the number of expirations that have occurred.
222 (The returned value is in host byte order,
223 i.e., the native byte order for integers on the host machine.)
225 If no timer expirations have occurred at the time of the
227 then the call either blocks until the next timer expiration,
228 or fails with the error
230 if the file descriptor has been made nonblocking
240 will fail with the error
242 if the size of the supplied buffer is less than 8 bytes.
244 .BR poll "(2), " select "(2) (and similar)"
245 The file descriptor is readable
253 if one or more timer expirations have occurred.
255 The file descriptor also supports the other file-descriptor
263 When the file descriptor is no longer required it should be closed.
264 When all file descriptors associated with the same timer object
266 the timer is disarmed and its resources are freed by the kernel.
268 .SS fork(2) semantics
271 the child inherits a copy of the file descriptor created by
272 .BR timerfd_create ().
273 The file descriptor refers to the same underlying
274 timer object as the corresponding file descriptor in the parent,
277 in the child will return information about
278 expirations of the timer.
280 .SS execve(2) semantics
281 A file descriptor created by
282 .BR timerfd_create ()
285 and continues to generate timer expirations if the timer was armed.
288 .BR timerfd_create ()
289 returns a new file descriptor.
290 On error, \-1 is returned and
292 is set to indicate the error.
294 .BR timerfd_settime ()
296 .BR timerfd_gettime ()
298 on error they return \-1, and set
300 to indicate the error.
302 .BR timerfd_create ()
303 can fail with the following errors:
316 or, in Linux 2.6.26 or earlier,
321 The per-process limit of open file descriptors has been reached.
324 The system-wide limit on the total number of open files has been
328 Could not mount (internal) anonymous inode device.
331 There was insufficient kernel memory to create the timer.
333 .BR timerfd_settime ()
335 .BR timerfd_gettime ()
336 can fail with the following errors:
340 is not a valid file descriptor.
347 is not valid a pointer.
351 is not a valid timerfd file descriptor.
353 .BR timerfd_settime ()
354 can also fail with the following errors:
358 is not properly initialized (one of the
360 falls outside the range zero to 999,999,999).
363 .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
364 .\" In older kernel versions, no check was made for invalid flags.
368 These system calls are available on Linux since kernel 2.6.25.
369 Library support is provided by glibc since version 2.8.
371 These system calls are Linux-specific.
376 .BR timerfd_create ()
377 supports fewer types of clock IDs than
378 .BR timer_create (2).
381 The following program creates a timer and then monitors its progress.
382 The program accepts up to three command-line arguments.
383 The first argument specifies the number of seconds for
384 the initial expiration of the timer.
385 The second argument specifies the interval for the timer, in seconds.
386 The third argument specifies the number of times the program should
387 allow the timer to expire before terminating.
388 The second and third command-line arguments are optional.
390 The following shell session demonstrates the use of the program:
394 .RB "$" " a.out 3 1 100"
396 3.000: read: 1; total=1
397 4.000: read: 1; total=2
398 .BR "^Z " " # type control-Z to suspend the program"
399 [1]+ Stopped ./timerfd3_demo 3 1 100
400 .RB "$ " "fg" " # Resume execution after a few seconds"
402 9.660: read: 5; total=7
403 10.000: read: 1; total=8
404 11.000: read: 1; total=9
405 .BR "^C " " # type control-C to suspend the program"
411 .\" The commented out code here is what we currently need until
412 .\" the required stuff is in glibc
415 .\"/* Link with -lrt */
416 .\"#define _GNU_SOURCE
417 .\"#include <sys/syscall.h>
418 .\"#include <unistd.h>
420 .\"#if defined(__i386__)
421 .\"#define __NR_timerfd_create 322
422 .\"#define __NR_timerfd_settime 325
423 .\"#define __NR_timerfd_gettime 326
427 .\"timerfd_create(int clockid, int flags)
429 .\" return syscall(__NR_timerfd_create, clockid, flags);
433 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
434 .\" struct itimerspec *curr_value)
436 .\" return syscall(__NR_timerfd_settime, fd, flags, new_value,
441 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
443 .\" return syscall(__NR_timerfd_gettime, fd, curr_value);
446 .\"#define TFD_TIMER_ABSTIME (1 << 0)
448 .\"////////////////////////////////////////////////////////////
449 #include <sys/timerfd.h>
454 #include <stdint.h> /* Definition of uint64_t */
456 #define handle_error(msg) \\
457 do { perror(msg); exit(EXIT_FAILURE); } while (0)
460 print_elapsed_time(void)
462 static struct timespec start;
463 struct timespec curr;
464 static int first_call = 1;
469 if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
470 handle_error("clock_gettime");
473 if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
474 handle_error("clock_gettime");
476 secs = curr.tv_sec \- start.tv_sec;
477 nsecs = curr.tv_nsec \- start.tv_nsec;
482 printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
486 main(int argc, char *argv[])
488 struct itimerspec new_value;
491 uint64_t exp, tot_exp;
494 if ((argc != 2) && (argc != 4)) {
495 fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n",
500 if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
501 handle_error("clock_gettime");
503 /* Create a CLOCK_REALTIME absolute timer with initial
504 expiration and interval as specified in command line */
506 new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
507 new_value.it_value.tv_nsec = now.tv_nsec;
509 new_value.it_interval.tv_sec = 0;
512 new_value.it_interval.tv_sec = atoi(argv[2]);
513 max_exp = atoi(argv[3]);
515 new_value.it_interval.tv_nsec = 0;
517 fd = timerfd_create(CLOCK_REALTIME, 0);
519 handle_error("timerfd_create");
521 if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
522 handle_error("timerfd_settime");
524 print_elapsed_time();
525 printf("timer started\\n");
527 for (tot_exp = 0; tot_exp < max_exp;) {
528 s = read(fd, &exp, sizeof(uint64_t));
529 if (s != sizeof(uint64_t))
530 handle_error("read");
533 print_elapsed_time();
534 printf("read: %llu; total=%llu\\n",
535 (unsigned long long) exp,
536 (unsigned long long) tot_exp);
550 .BR timer_create (2),
551 .BR timer_gettime (2),
552 .BR timer_settime (2),