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 be
36 either CLOCK_REALTIME or CLOCK_MONOTONIC. CLOCK_REALTIME is a settable
37 system-wide clock. CLOCK_MONOTONIC is a nonsettable clock that is not
38 affected by discontinuous changes in the system clock (e.g., manual
39 changes to system time). The current value of each of these clocks can
40 be retrieved using clock_gettime(2).
41 Starting with Linux 2.6.27, the following values may be bitwise ORed in
43 flags to change the behavior of timerfd_create():
44 TFD_NONBLOCK Set the O_NONBLOCK file status flag on the new open file
46 description. Using this flag saves extra calls to
47 fcntl(2) to achieve the same result.
48 TFD_CLOEXEC Set the close-on-exec (FD_CLOEXEC) flag on the new file
50 descriptor. See the description of the O_CLOEXEC flag in
51 open(2) for reasons why this may be useful.
52 In Linux versions up to and including 2.6.26, flags must be specified
54 as zero.
55 timerfd_settime()
57 timerfd_settime() arms (starts) or disarms (stops) the timer referred
58 to by the file descriptor fd.
59 The new_value argument specifies the initial expiration and interval
61 for the timer. The itimer structure used for this argument contains
62 two fields, each of which is in turn a structure of type timespec:
63 struct timespec {
65 time_t tv_sec; /* Seconds */
66 long tv_nsec; /* Nanoseconds */
67 };
68 struct itimerspec {
70 struct timespec it_interval; /* Interval for periodic timer */
71 struct timespec it_value; /* Initial expiration */
72 };
73 new_value.it_value specifies the initial expiration of the timer, in
75 seconds and nanoseconds. Setting either field of new_value.it_value to
76 a nonzero value arms the timer. Setting both fields of
77 new_value.it_value to zero disarms the timer.
78 Setting one or both fields of new_value.it_interval to nonzero values
80 specifies the period, in seconds and nanoseconds, for repeated timer
81 expirations after the initial expiration. If both fields of
82 new_value.it_interval are zero, the timer expires just once, at the
83 time specified by new_value.it_value.
84 The flags argument is either 0, to start a relative timer
86 (new_value.it_interval specifies a time relative to the current value
87 of the clock specified by clockid), or TFD_TIMER_ABSTIME, to start an
88 absolute timer (new_value.it_value specifies an absolute time for the
89 clock specified by clockid; that is, the timer will expire when the
90 value of that clock reaches the value specified in new_value.it_value).
91 The old_value argument returns a structure containing the setting of
93 the timer that was current at the time of the call; see the description
94 of timerfd_gettime() following.
95 timerfd_gettime()
97 timerfd_gettime() returns, in curr_value, an itimerspec structure that
98 contains the current setting of the timer referred to by the file
99 descriptor fd.
100 The it_value field returns the amount of time until the timer will next
102 expire. If both fields of this structure are zero, then the timer is
103 currently disarmed. This field always contains a relative value,
104 regardless of whether the TFD_TIMER_ABSTIME flag was specified when
105 setting the timer.
106 The it_interval field returns the interval of the timer. If both
108 fields of this structure are zero, then the timer is set to expire just
109 once, at the time specified by curr_value.it_value.
110 Operating on a timer file descriptor
112 The file descriptor returned by timerfd_create() supports the following
113 operations:
114 read(2)
116 If the timer has already expired one or more times since its
117 settings were last modified using timerfd_settime(), or since
118 the last successful read(2), then the buffer given to read(2)
119 returns an unsigned 8-byte integer (uint64_t) containing the
120 number of expirations that have occurred. (The returned value
121 is in host byte order, i.e., the native byte order for integers
122 on the host machine.)
123 If no timer expirations have occurred at the time of the
125 read(2), then the call either blocks until the next timer expi‐
126 ration, or fails with the error EAGAIN if the file descriptor
127 has been made nonblocking (via the use of the fcntl(2) F_SETFL
128 operation to set the O_NONBLOCK flag).
129 A read(2) will fail with the error EINVAL if the size of the
131 supplied buffer is less than 8 bytes.
132 poll(2), select(2) (and similar)
134 The file descriptor is readable (the select(2) readfds argument;
135 the poll(2) POLLIN flag) if one or more timer expirations have
136 occurred.
137 The file descriptor also supports the other file-descriptor mul‐
139 tiplexing APIs: pselect(2), ppoll(2), and epoll(7).
140 close(2)
142 When the file descriptor is no longer required it should be
143 closed. When all file descriptors associated with the same
144 timer object have been closed, the timer is disarmed and its
145 resources are freed by the kernel.
146 fork(2) semantics
148 After a fork(2), the child inherits a copy of the file descriptor cre‐
149 ated by timerfd_create(). The file descriptor refers to the same
150 underlying timer object as the corresponding file descriptor in the
151 parent, and read(2)s in the child will return information about expira‐
152 tions of the timer.
153 execve(2) semantics
155 A file descriptor created by timerfd_create() is preserved across
156 execve(2), and continues to generate timer expirations if the timer was
157 armed.
158
160 On success, timerfd_create() returns a new file descriptor. On error,
161 -1 is returned and errno is set to indicate the error.
162 timerfd_settime() and timerfd_gettime() return 0 on success; on error
164 they return -1, and set errno to indicate the error.
165
167 timerfd_create() can fail with the following errors:
168 EINVAL The clockid argument is neither CLOCK_MONOTONIC nor CLOCK_REAL‐
170 TIME;
171 EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is
173 nonzero.
174 EMFILE The per-process limit of open file descriptors has been reached.
176 ENFILE The system-wide limit on the total number of open files has been
178 reached.
179 ENODEV Could not mount (internal) anonymous inode device.
181 ENOMEM There was insufficient kernel memory to create the timer.
183 timerfd_settime() and timerfd_gettime() can fail with the following
185 errors:
186 EBADF fd is not a valid file descriptor.
188 EFAULT new_value, old_value, or curr_value is not valid a pointer.
190 EINVAL fd is not a valid timerfd file descriptor.
192 timerfd_settime() can also fail with the following errors:
194 EINVAL new_value is not properly initialized (one of the tv_nsec falls
196 outside the range zero to 999,999,999).
197 EINVAL flags is invalid.
199
201 These system calls are available on Linux since kernel 2.6.25. Library
202 support is provided by glibc since version 2.8.
203
205 These system calls are Linux-specific.
206
208 The following program creates a timer and then monitors its progress.
209 The program accepts up to three command-line arguments. The first
210 argument specifies the number of seconds for the initial expiration of
211 the timer. The second argument specifies the interval for the timer,
212 in seconds. The third argument specifies the number of times the pro‐
213 gram should allow the timer to expire before terminating. The second
214 and third command-line arguments are optional.
215 The following shell session demonstrates the use of the program:
217 $ a.out 3 1 100
219 0.000: timer started
220 3.000: read: 1; total=1
221 4.000: read: 1; total=2
222 ^Z # type control-Z to suspend the program
223 [1]+ Stopped ./timerfd3_demo 3 1 100
224 $ fg # Resume execution after a few seconds
225 a.out 3 1 100
226 9.660: read: 5; total=7
227 10.000: read: 1; total=8
228 11.000: read: 1; total=9
229 ^C # type control-C to suspend the program
230 Program source
232 #include <sys/timerfd.h>
234 #include <time.h>
235 #include <unistd.h>
236 #include <stdlib.h>
237 #include <stdio.h>
238 #include <stdint.h> /* Definition of uint64_t */
239 #define handle_error(msg) \
241 do { perror(msg); exit(EXIT_FAILURE); } while (0)
242 static void
244 print_elapsed_time(void)
245 {
246 static struct timespec start;
247 struct timespec curr;
248 static int first_call = 1;
249 int secs, nsecs;
250 if (first_call) {
252 first_call = 0;
253 if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
254 handle_error("clock_gettime");
255 }
256 if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
258 handle_error("clock_gettime");
259 secs = curr.tv_sec - start.tv_sec;
261 nsecs = curr.tv_nsec - start.tv_nsec;
262 if (nsecs < 0) {
263 secs--;
264 nsecs += 1000000000;
265 }
266 printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
267 }
268 int
270 main(int argc, char *argv[])
271 {
272 struct itimerspec new_value;
273 int max_exp, fd;
274 struct timespec now;
275 uint64_t exp, tot_exp;
276 ssize_t s;
277 if ((argc != 2) && (argc != 4)) {
279 fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",
280 argv[0]);
281 exit(EXIT_FAILURE);
282 }
283 if (clock_gettime(CLOCK_REALTIME, &now) == -1)
285 handle_error("clock_gettime");
286 /* Create a CLOCK_REALTIME absolute timer with initial
288 expiration and interval as specified in command line */
289 new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
291 new_value.it_value.tv_nsec = now.tv_nsec;
292 if (argc == 2) {
293 new_value.it_interval.tv_sec = 0;
294 max_exp = 1;
295 } else {
296 new_value.it_interval.tv_sec = atoi(argv[2]);
297 max_exp = atoi(argv[3]);
298 }
299 new_value.it_interval.tv_nsec = 0;
300 fd = timerfd_create(CLOCK_REALTIME, 0);
302 if (fd == -1)
303 handle_error("timerfd_create");
304 if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
306 handle_error("timerfd_settime");
307 print_elapsed_time();
309 printf("timer started\n");
310 for (tot_exp = 0; tot_exp < max_exp;) {
312 s = read(fd, &exp, sizeof(uint64_t));
313 if (s != sizeof(uint64_t))
314 handle_error("read");
315 tot_exp += exp;
317 print_elapsed_time();
318 printf("read: %llu; total=%llu\n",
319 (unsigned long long) exp,
320 (unsigned long long) tot_exp);
321 }
322 exit(EXIT_SUCCESS);
324 }
325
327 Currently, timerfd_create() supports fewer types of clock IDs than
328 timer_create(2).
329
331 eventfd(2), poll(2), read(2), select(2), setitimer(2), signalfd(2),
332 timer_create(2), timer_gettime(2), timer_settime(2), epoll(7), time(7)
333
335 This page is part of release 3.25 of the Linux man-pages project. A
336 description of the project, and information about reporting bugs, can
337 be found at http://www.kernel.org/doc/man-pages/.
338Linux 2009-03-10 TIMERFD_CREATE(2)