1TIMERFD_CREATE(2) Linux Programmer's Manual TIMERFD_CREATE(2)
2
6 timerfd_create, timerfd_settime, timerfd_gettime - timers that notify
7 via file descriptors
8
10 #include <sys/timerfd.h>
11 int timerfd_create(int clockid, int flags);
13 int timerfd_settime(int fd, int flags,
15 const struct itimerspec *new_value,
16 struct itimerspec *old_value);
17 int timerfd_gettime(int fd, struct itimerspec *curr_value);
19
21 These system calls create and operate on a timer that delivers timer
22 expiration notifications via a file descriptor. They provide an alter‐
23 native to the use of setitimer(2) or timer_create(2), with the advan‐
24 tage that the file descriptor may be monitored by select(2), poll(2),
25 and epoll(7).
26 The use of these three system calls is analogous to the use of
28 timer_create(2), timer_settime(2), and timer_gettime(2). (There is no
29 analog of timer_getoverrun(2), since that functionality is provided by
30 read(2), as described below.)
31 timerfd_create()
33 timerfd_create() creates a new timer object, and returns a file
34 descriptor that refers to that timer. The clockid argument specifies
35 the clock that is used to mark the progress of the timer, and must one
36 of the following:
37 CLOCK_REALTIME
39 A settable system-wide real-time clock.
40 CLOCK_MONOTONIC
42 A nonsettable monotonically increasing clock that measures time
43 from some unspecified point in the past that does not change
44 after system startup.
45 CLOCK_BOOTTIME (Since Linux 3.15)
47 Like CLOCK_MONOTONIC, this is a monotonically increasing clock.
48 However, whereas the CLOCK_MONOTONIC clock does not measure the
49 time while a system is suspended, the CLOCK_BOOTTIME clock does
50 include the time during which the system is suspended. This is
51 useful for applications that need to be suspend-aware.
52 CLOCK_REALTIME is not suitable for such applications, since that
53 clock is affected by discontinuous changes to the system clock.
54 CLOCK_REALTIME_ALARM (since Linux 3.11)
56 This clock is like CLOCK_REALTIME, but will wake the system if
57 it is suspended. The caller must have the CAP_WAKE_ALARM capa‐
58 bility in order to set a timer against this clock.
59 CLOCK_BOOTTIME_ALARM (since Linux 3.11)
61 This clock is like CLOCK_BOOTTIME, but will wake the system if
62 it is suspended. The caller must have the CAP_WAKE_ALARM capa‐
63 bility in order to set a timer against this clock.
64 The current value of each of these clocks can be retrieved using
66 clock_gettime(2).
67 Starting with Linux 2.6.27, the following values may be bitwise ORed in
69 flags to change the behavior of timerfd_create():
70 TFD_NONBLOCK Set the O_NONBLOCK file status flag on the new open file
72 description. Using this flag saves extra calls to
73 fcntl(2) to achieve the same result.
74 TFD_CLOEXEC Set the close-on-exec (FD_CLOEXEC) flag on the new file
76 descriptor. See the description of the O_CLOEXEC flag in
77 open(2) for reasons why this may be useful.
78 In Linux versions up to and including 2.6.26, flags must be specified
80 as zero.
81 timerfd_settime()
83 timerfd_settime() arms (starts) or disarms (stops) the timer referred
84 to by the file descriptor fd.
85 The new_value argument specifies the initial expiration and interval
87 for the timer. The itimerspec structure used for this argument con‐
88 tains two fields, each of which is in turn a structure of type time‐
89 spec:
90 struct timespec {
92 time_t tv_sec; /* Seconds */
93 long tv_nsec; /* Nanoseconds */
94 };
95 struct itimerspec {
97 struct timespec it_interval; /* Interval for periodic timer */
98 struct timespec it_value; /* Initial expiration */
99 };
100 new_value.it_value specifies the initial expiration of the timer, in
102 seconds and nanoseconds. Setting either field of new_value.it_value to
103 a nonzero value arms the timer. Setting both fields of
104 new_value.it_value to zero disarms the timer.
105 Setting one or both fields of new_value.it_interval to nonzero values
107 specifies the period, in seconds and nanoseconds, for repeated timer
108 expirations after the initial expiration. If both fields of
109 new_value.it_interval are zero, the timer expires just once, at the
110 time specified by new_value.it_value.
111 By default, the initial expiration time specified in new_value is
113 interpreted relative to the current time on the timer's clock at the
114 time of the call (i.e., new_value.it_value specifies a time relative to
115 the current value of the clock specified by clockid). An absolute
116 timeout can be selected via the flags argument.
117 The flags argument is a bit mask that can include the following values:
119 TFD_TIMER_ABSTIME
121 Interpret new_value.it_value as an absolute value on the timer's
122 clock. The timer will expire when the value of the timer's
123 clock reaches the value specified in new_value.it_value.
124 TFD_TIMER_CANCEL_ON_SET
126 If this flag is specified along with TFD_TIMER_ABSTIME and the
127 clock for this timer is CLOCK_REALTIME or CLOCK_REALTIME_ALARM,
128 then mark this timer as cancelable if the real-time clock under‐
129 goes a discontinuous change (settimeofday(2), clock_settime(2),
130 or similar). When such changes occur, a current or future
131 read(2) from the file descriptor will fail with the error ECAN‐
132 CELED.
133 If the old_value argument is not NULL, then the itimerspec structure
135 that it points to is used to return the setting of the timer that was
136 current at the time of the call; see the description of timerfd_get‐
137 time() following.
138 timerfd_gettime()
140 timerfd_gettime() returns, in curr_value, an itimerspec structure that
141 contains the current setting of the timer referred to by the file
142 descriptor fd.
143 The it_value field returns the amount of time until the timer will next
145 expire. If both fields of this structure are zero, then the timer is
146 currently disarmed. This field always contains a relative value,
147 regardless of whether the TFD_TIMER_ABSTIME flag was specified when
148 setting the timer.
149 The it_interval field returns the interval of the timer. If both
151 fields of this structure are zero, then the timer is set to expire just
152 once, at the time specified by curr_value.it_value.
153 Operating on a timer file descriptor
155 The file descriptor returned by timerfd_create() supports the following
156 operations:
157 read(2)
159 If the timer has already expired one or more times since its
160 settings were last modified using timerfd_settime(), or since
161 the last successful read(2), then the buffer given to read(2)
162 returns an unsigned 8-byte integer (uint64_t) containing the
163 number of expirations that have occurred. (The returned value
164 is in host byte order—that is, the native byte order for inte‐
165 gers on the host machine.)
166 If no timer expirations have occurred at the time of the
168 read(2), then the call either blocks until the next timer expi‐
169 ration, or fails with the error EAGAIN if the file descriptor
170 has been made nonblocking (via the use of the fcntl(2) F_SETFL
171 operation to set the O_NONBLOCK flag).
172 A read(2) fails with the error EINVAL if the size of the sup‐
174 plied buffer is less than 8 bytes.
175 If the associated clock is either CLOCK_REALTIME or CLOCK_REAL‐
177 TIME_ALARM, the timer is absolute (TFD_TIMER_ABSTIME), and the
178 flag TFD_TIMER_CANCEL_ON_SET was specified when calling
179 timerfd_settime(), then read(2) fails with the error ECANCELED
180 if the real-time clock undergoes a discontinuous change. (This
181 allows the reading application to discover such discontinuous
182 changes to the clock.)
183 poll(2), select(2) (and similar)
185 The file descriptor is readable (the select(2) readfds argument;
186 the poll(2) POLLIN flag) if one or more timer expirations have
187 occurred.
188 The file descriptor also supports the other file-descriptor mul‐
190 tiplexing APIs: pselect(2), ppoll(2), and epoll(7).
191 ioctl(2)
193 The following timerfd-specific command is supported:
194 TFD_IOC_SET_TICKS (since Linux 3.17)
196 Adjust the number of timer expirations that have
197 occurred. The argument is a pointer to a nonzero 8-byte
198 integer (uint64_t*) containing the new number of expira‐
199 tions. Once the number is set, any waiter on the timer
200 is woken up. The only purpose of this command is to
201 restore the expirations for the purpose of check‐
202 point/restore. This operation is available only if the
203 kernel was configured with the CONFIG_CHECKPOINT_RESTORE
204 option.
205 close(2)
207 When the file descriptor is no longer required it should be
208 closed. When all file descriptors associated with the same
209 timer object have been closed, the timer is disarmed and its
210 resources are freed by the kernel.
211 fork(2) semantics
213 After a fork(2), the child inherits a copy of the file descriptor cre‐
214 ated by timerfd_create(). The file descriptor refers to the same
215 underlying timer object as the corresponding file descriptor in the
216 parent, and read(2)s in the child will return information about expira‐
217 tions of the timer.
218 execve(2) semantics
220 A file descriptor created by timerfd_create() is preserved across
221 execve(2), and continues to generate timer expirations if the timer was
222 armed.
223
225 On success, timerfd_create() returns a new file descriptor. On error,
226 -1 is returned and errno is set to indicate the error.
227 timerfd_settime() and timerfd_gettime() return 0 on success; on error
229 they return -1, and set errno to indicate the error.
230
232 timerfd_create() can fail with the following errors:
233 EINVAL The clockid argument is neither CLOCK_MONOTONIC nor CLOCK_REAL‐
235 TIME;
236 EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is
238 nonzero.
239 EMFILE The per-process limit on the number of open file descriptors has
241 been reached.
242 ENFILE The system-wide limit on the total number of open files has been
244 reached.
245 ENODEV Could not mount (internal) anonymous inode device.
247 ENOMEM There was insufficient kernel memory to create the timer.
249 timerfd_settime() and timerfd_gettime() can fail with the following
251 errors:
252 EBADF fd is not a valid file descriptor.
254 EFAULT new_value, old_value, or curr_value is not valid a pointer.
256 EINVAL fd is not a valid timerfd file descriptor.
258 timerfd_settime() can also fail with the following errors:
260 EINVAL new_value is not properly initialized (one of the tv_nsec falls
262 outside the range zero to 999,999,999).
263 EINVAL flags is invalid.
265
267 These system calls are available on Linux since kernel 2.6.25. Library
268 support is provided by glibc since version 2.8.
269
271 These system calls are Linux-specific.
272
274 Currently, timerfd_create() supports fewer types of clock IDs than
275 timer_create(2).
276
278 The following program creates a timer and then monitors its progress.
279 The program accepts up to three command-line arguments. The first
280 argument specifies the number of seconds for the initial expiration of
281 the timer. The second argument specifies the interval for the timer,
282 in seconds. The third argument specifies the number of times the pro‐
283 gram should allow the timer to expire before terminating. The second
284 and third command-line arguments are optional.
285 The following shell session demonstrates the use of the program:
287 $ a.out 3 1 100
289 0.000: timer started
290 3.000: read: 1; total=1
291 4.000: read: 1; total=2
292 ^Z # type control-Z to suspend the program
293 [1]+ Stopped ./timerfd3_demo 3 1 100
294 $ fg # Resume execution after a few seconds
295 a.out 3 1 100
296 9.660: read: 5; total=7
297 10.000: read: 1; total=8
298 11.000: read: 1; total=9
299 ^C # type control-C to suspend the program
300 Program source
302 #include <sys/timerfd.h>
304 #include <time.h>
305 #include <unistd.h>
306 #include <stdlib.h>
307 #include <stdio.h>
308 #include <stdint.h> /* Definition of uint64_t */
309 #define handle_error(msg) \
311 do { perror(msg); exit(EXIT_FAILURE); } while (0)
312 static void
314 print_elapsed_time(void)
315 {
316 static struct timespec start;
317 struct timespec curr;
318 static int first_call = 1;
319 int secs, nsecs;
320 if (first_call) {
322 first_call = 0;
323 if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
324 handle_error("clock_gettime");
325 }
326 if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
328 handle_error("clock_gettime");
329 secs = curr.tv_sec - start.tv_sec;
331 nsecs = curr.tv_nsec - start.tv_nsec;
332 if (nsecs < 0) {
333 secs--;
334 nsecs += 1000000000;
335 }
336 printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
337 }
338 int
340 main(int argc, char *argv[])
341 {
342 struct itimerspec new_value;
343 int max_exp, fd;
344 struct timespec now;
345 uint64_t exp, tot_exp;
346 ssize_t s;
347 if ((argc != 2) && (argc != 4)) {
349 fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",
350 argv[0]);
351 exit(EXIT_FAILURE);
352 }
353 if (clock_gettime(CLOCK_REALTIME, &now) == -1)
355 handle_error("clock_gettime");
356 /* Create a CLOCK_REALTIME absolute timer with initial
358 expiration and interval as specified in command line */
359 new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
361 new_value.it_value.tv_nsec = now.tv_nsec;
362 if (argc == 2) {
363 new_value.it_interval.tv_sec = 0;
364 max_exp = 1;
365 } else {
366 new_value.it_interval.tv_sec = atoi(argv[2]);
367 max_exp = atoi(argv[3]);
368 }
369 new_value.it_interval.tv_nsec = 0;
370 fd = timerfd_create(CLOCK_REALTIME, 0);
372 if (fd == -1)
373 handle_error("timerfd_create");
374 if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
376 handle_error("timerfd_settime");
377 print_elapsed_time();
379 printf("timer started\n");
380 for (tot_exp = 0; tot_exp < max_exp;) {
382 s = read(fd, &exp, sizeof(uint64_t));
383 if (s != sizeof(uint64_t))
384 handle_error("read");
385 tot_exp += exp;
387 print_elapsed_time();
388 printf("read: %llu; total=%llu\n",
389 (unsigned long long) exp,
390 (unsigned long long) tot_exp);
391 }
392 exit(EXIT_SUCCESS);
394 }
395
397 eventfd(2), poll(2), read(2), select(2), setitimer(2), signalfd(2),
398 timer_create(2), timer_gettime(2), timer_settime(2), epoll(7), time(7)
399
401 This page is part of release 4.16 of the Linux man-pages project. A
402 description of the project, information about reporting bugs, and the
403 latest version of this page, can be found at
404 https://www.kernel.org/doc/man-pages/.
405Linux 2017-09-15 TIMERFD_CREATE(2)