Debian Codegraph @

upstream/debian-unstable/man2/timerfd_create.2

raw
1 .\" Copyright 2008, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH timerfd_create 2 2026-02-16 "Linux man-pages 6.18"
7 .SH NAME
8 timerfd_create, timerfd_settime, timerfd_gettime \-
9 timers that notify via file descriptors
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/timerfd.h>
16 .P
17 .BI "int timerfd_create(int " clockid ", int " flags );
18 .P
19 .BI "int timerfd_settime(int " fd ", int " flags ,
20 .BI " const struct itimerspec *" new_value ,
21 .BI " struct itimerspec *_Nullable " old_value );
22 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
23 .fi
24 .SH DESCRIPTION
25 These system calls create and operate on a timer
26 that delivers timer expiration notifications via a file descriptor.
27 They provide an alternative to the use of
28 .BR setitimer (2)
29 or
30 .BR timer_create (2),
31 with the advantage that the file descriptor may be monitored by
32 .BR select (2),
33 .BR poll (2),
34 and
35 .BR epoll (7).
36 .P
37 The use of these three system calls is analogous to the use of
38 .BR timer_create (2),
39 .BR timer_settime (2),
40 and
41 .BR timer_gettime (2).
42 (There is no analog of
43 .BR timer_getoverrun (2),
44 since that functionality is provided by
45 .BR read (2),
46 as described below.)
47 .\"
48 .SS timerfd_create()
49 .BR timerfd_create ()
50 creates a new timer object,
51 and returns a file descriptor that refers to that timer.
52 The
53 .I clockid
54 argument specifies the clock that is used to mark the progress
55 of the timer, and must be one of the following:
56 .TP
57 .B CLOCK_REALTIME
58 A settable system-wide real-time clock.
59 .TP
60 .B CLOCK_MONOTONIC
61 A nonsettable monotonically increasing clock that measures time
62 from some unspecified point in the past that does not change
63 after system startup.
64 .TP
65 .BR CLOCK_BOOTTIME " (Since Linux 3.15)"
66 .\" commit 4a2378a943f09907fb1ae35c15de917f60289c14
67 Like
68 .BR CLOCK_MONOTONIC ,
69 this is a monotonically increasing clock.
70 However, whereas the
71 .B CLOCK_MONOTONIC
72 clock does not measure the time while a system is suspended, the
73 .B CLOCK_BOOTTIME
74 clock does include the time during which the system is suspended.
75 This is useful for applications that need to be suspend-aware.
76 .B CLOCK_REALTIME
77 is not suitable for such applications, since that clock is affected
78 by discontinuous changes to the system clock.
79 .TP
80 .BR CLOCK_REALTIME_ALARM " (since Linux 3.11)"
81 .\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8
82 This clock is like
83 .BR CLOCK_REALTIME ,
84 but will wake the system if it is suspended.
85 The caller must have the
86 .B CAP_WAKE_ALARM
87 capability in order to set a timer against this clock.
88 .TP
89 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.11)"
90 .\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8
91 This clock is like
92 .BR CLOCK_BOOTTIME ,
93 but will wake the system if it is suspended.
94 The caller must have the
95 .B CAP_WAKE_ALARM
96 capability in order to set a timer against this clock.
97 .P
98 See
99 .BR clock_getres (2)
100 for some further details on the above clocks.
101 .P
102 The current value of each of these clocks can be retrieved using
103 .BR clock_gettime (2).
104 .P
105 Starting with Linux 2.6.27, the following values may be bitwise ORed in
106 .I flags
107 to change the behavior of
108 .BR timerfd_create ():
109 .TP 14
110 .B TFD_NONBLOCK
111 Set the
112 .B O_NONBLOCK
113 file status flag on the open file description (see
114 .BR open (2))
115 referred to by the new file descriptor.
116 Using this flag saves extra calls to
117 .BR fcntl (2)
118 to achieve the same result.
119 .TP
120 .B TFD_CLOEXEC
121 Set the close-on-exec
122 .RB ( FD_CLOEXEC )
123 flag on the new file descriptor.
124 See the description of the
125 .B O_CLOEXEC
126 flag in
127 .BR open (2)
128 for reasons why this may be useful.
129 .P
130 In Linux versions up to and including 2.6.26,
131 .I flags
132 must be specified as zero.
133 .SS timerfd_settime()
134 .BR timerfd_settime ()
135 arms (starts) or disarms (stops)
136 the timer referred to by the file descriptor
137 .IR fd .
138 .P
139 The
140 .I new_value
141 argument specifies the initial expiration and interval for the timer.
142 The
143 .I itimerspec
144 structure used for this argument is described in
145 .BR itimerspec (3type).
146 .P
147 .I new_value.it_value
148 specifies the initial expiration of the timer,
149 in seconds and nanoseconds.
150 Setting either field of
151 .I new_value.it_value
152 to a nonzero value arms the timer.
153 Setting both fields of
154 .I new_value.it_value
155 to zero disarms the timer.
156 .P
157 Setting one or both fields of
158 .I new_value.it_interval
159 to nonzero values specifies the period, in seconds and nanoseconds,
160 for repeated timer expirations after the initial expiration.
161 If both fields of
162 .I new_value.it_interval
163 are zero, the timer expires just once, at the time specified by
164 .IR new_value.it_value .
165 .P
166 By default,
167 the initial expiration time specified in
168 .I new_value
169 is interpreted relative to the current time
170 on the timer's clock at the time of the call (i.e.,
171 .I new_value.it_value
172 specifies a time relative to the current value of the clock specified by
173 .IR clockid ).
174 An absolute timeout can be selected via the
175 .I flags
176 argument.
177 .P
178 The
179 .I flags
180 argument is a bit mask that can include the following values:
181 .TP
182 .B TFD_TIMER_ABSTIME
183 Interpret
184 .I new_value.it_value
185 as an absolute value on the timer's clock.
186 The timer will expire when the value of the timer's
187 clock reaches the value specified in
188 .IR new_value.it_value .
189 .TP
190 .B TFD_TIMER_CANCEL_ON_SET
191 If this flag is specified along with
192 .B TFD_TIMER_ABSTIME
193 and the clock for this timer is
194 .B CLOCK_REALTIME
195 or
196 .BR CLOCK_REALTIME_ALARM ,
197 then mark this timer as cancelable if the real-time clock
198 undergoes a discontinuous change
199 .RB ( settimeofday (2),
200 .BR clock_settime (2),
201 or similar).
202 When such changes occur, a current or future
203 .BR read (2)
204 from the file descriptor will fail with the error
205 .BR ECANCELED .
206 .P
207 If the
208 .I old_value
209 argument is not NULL, then the
210 .I itimerspec
211 structure that it points to is used to return the setting of the timer
212 that was current at the time of the call;
213 see the description of
214 .BR timerfd_gettime ()
215 following.
216 .\"
217 .SS timerfd_gettime()
218 .BR timerfd_gettime ()
219 returns, in
220 .IR curr_value ,
221 an
222 .I itimerspec
223 structure that contains the current setting of the timer
224 referred to by the file descriptor
225 .IR fd .
226 .P
227 The
228 .I it_value
229 field returns the amount of time
230 until the timer will next expire.
231 If both fields of this structure are zero,
232 then the timer is currently disarmed.
233 This field always contains a relative value, regardless of whether the
234 .B TFD_TIMER_ABSTIME
235 flag was specified when setting the timer.
236 .P
237 The
238 .I it_interval
239 field returns the interval of the timer.
240 If both fields of this structure are zero,
241 then the timer is set to expire just once, at the time specified by
242 .IR curr_value.it_value .
243 .SS Operating on a timer file descriptor
244 The file descriptor returned by
245 .BR timerfd_create ()
246 supports the following additional operations:
247 .TP
248 .BR read (2)
249 If the timer has already expired one or more times since
250 its settings were last modified using
251 .BR timerfd_settime (),
252 or since the last successful
253 .BR read (2),
254 then the buffer given to
255 .BR read (2)
256 returns an unsigned 8-byte integer
257 .RI ( uint64_t )
258 containing the number of expirations that have occurred.
259 (The returned value is in host byte order\[em]that is,
260 the native byte order for integers on the host machine.)
261 .IP
262 If no timer expirations have occurred at the time of the
263 .BR read (2),
264 then the call either blocks until the next timer expiration,
265 or fails with the error
266 .B EAGAIN
267 if the file descriptor has been made nonblocking
268 (via the use of the
269 .BR fcntl (2)
270 .B F_SETFL
271 operation to set the
272 .B O_NONBLOCK
273 flag).
274 .IP
275 A
276 .BR read (2)
277 fails with the error
278 .B EINVAL
279 if the size of the supplied buffer is less than 8 bytes.
280 .IP
281 If the associated clock is either
282 .B CLOCK_REALTIME
283 or
284 .BR CLOCK_REALTIME_ALARM ,
285 the timer is absolute
286 .RB ( TFD_TIMER_ABSTIME ),
287 and the flag
288 .B TFD_TIMER_CANCEL_ON_SET
289 was specified when calling
290 .BR timerfd_settime (),
291 then
292 .BR read (2)
293 fails with the error
294 .B ECANCELED
295 if the real-time clock undergoes a discontinuous change.
296 (This allows the reading application to discover
297 such discontinuous changes to the clock.)
298 .IP
299 If the associated clock is either
300 .B CLOCK_REALTIME
301 or
302 .BR CLOCK_REALTIME_ALARM ,
303 the timer is absolute
304 .RB ( TFD_TIMER_ABSTIME ),
305 and the flag
306 .B TFD_TIMER_CANCEL_ON_SET
307 was
308 .I not
309 specified when calling
310 .BR timerfd_settime (),
311 then a discontinuous negative change to the clock (e.g.,
312 .BR clock_settime (2))
313 may cause
314 .BR read (2)
315 to unblock, but return a value of 0 (i.e., no bytes read),
316 if the clock change occurs after the time expired,
317 but before the
318 .BR read (2)
319 on the file descriptor.
320 .TP
321 .BR poll (2)
322 .TQ
323 .BR select (2)
324 .TQ
325 (and similar)
326 The file descriptor is readable
327 (the
328 .BR select (2)
329 .I readfds
330 argument;
331 the
332 .BR poll (2)
333 .B POLLIN
334 flag)
335 if one or more timer expirations have occurred.
336 .IP
337 The file descriptor also supports the other file-descriptor
338 multiplexing APIs:
339 .BR pselect (2),
340 .BR ppoll (2),
341 and
342 .BR epoll (7).
343 .TP
344 .BR ioctl (2)
345 The following timerfd-specific command is supported:
346 .RS
347 .TP
348 .BR TFD_IOC_SET_TICKS " (since Linux 3.17)"
349 .\" commit 5442e9fbd7c23172a1c9bc736629cd123a9923f0
350 Adjust the number of timer expirations that have occurred.
351 The argument is a pointer to a nonzero 8-byte integer
352 .RI ( uint64_t *)
353 containing the new number of expirations.
354 Once the number is set, any waiter on the timer is woken up.
355 The only purpose of this command is to restore the expirations
356 for the purpose of checkpoint/restore.
357 This operation is available only if the kernel was configured with the
358 .B CONFIG_CHECKPOINT_RESTORE
359 option.
360 .RE
361 .TP
362 .BR close (2)
363 When the file descriptor is no longer required it should be closed.
364 When all file descriptors associated with the same timer object
365 have been closed,
366 the timer is disarmed and its resources are freed by the kernel.
367 .\"
368 .SS fork(2) semantics
369 After a
370 .BR fork (2),
371 the child inherits a copy of the file descriptor created by
372 .BR timerfd_create ().
373 The file descriptor refers to the same underlying
374 timer object as the corresponding file descriptor in the parent,
375 and
376 .BR read (2)s
377 in the child will return information about
378 expirations of the timer.
379 .\"
380 .SS execve(2) semantics
381 A file descriptor created by
382 .BR timerfd_create ()
383 is preserved across
384 .BR execve (2),
385 and continues to generate timer expirations if the timer was armed.
386 .SH RETURN VALUE
387 On success,
388 .BR timerfd_create ()
389 returns a new file descriptor.
390 On error, \-1 is returned and
391 .I errno
392 is set to indicate the error.
393 .P
394 .BR timerfd_settime ()
395 and
396 .BR timerfd_gettime ()
397 return 0 on success;
398 on error they return \-1, and set
399 .I errno
400 to indicate the error.
401 .SH ERRORS
402 .BR timerfd_create ()
403 can fail with the following errors:
404 .TP
405 .B EINVAL
406 The
407 .I clockid
408 is not valid.
409 .TP
410 .B EINVAL
411 .I flags
412 is invalid;
413 or, in Linux 2.6.26 or earlier,
414 .I flags
415 is nonzero.
416 .TP
417 .B EMFILE
418 The per-process limit on the number of open file descriptors has been reached.
419 .TP
420 .B ENFILE
421 The system-wide limit on the total number of open files has been
422 reached.
423 .TP
424 .B ENODEV
425 Could not mount (internal) anonymous inode device.
426 .TP
427 .B ENOMEM
428 There was insufficient kernel memory to create the timer.
429 .TP
430 .B EPERM
431 .I clockid
432 was
433 .B CLOCK_REALTIME_ALARM
434 or
435 .B CLOCK_BOOTTIME_ALARM
436 but the caller did not have the
437 .B CAP_WAKE_ALARM
438 capability.
439 .P
440 .BR timerfd_settime ()
441 and
442 .BR timerfd_gettime ()
443 can fail with the following errors:
444 .TP
445 .B EBADF
446 .I fd
447 is not a valid file descriptor.
448 .TP
449 .B EFAULT
450 .IR new_value ,
451 .IR old_value ,
452 or
453 .I curr_value
454 is not a valid pointer.
455 .TP
456 .B EINVAL
457 .I fd
458 is not a valid timerfd file descriptor.
459 .P
460 .BR timerfd_settime ()
461 can also fail with the following errors:
462 .TP
463 .B ECANCELED
464 See NOTES.
465 .TP
466 .B EINVAL
467 .I new_value
468 is not properly initialized (one of the
469 .I tv_nsec
470 falls outside the range zero to 999,999,999).
471 .TP
472 .B EINVAL
473 .\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version.
474 .\" In older kernel versions, no check was made for invalid flags.
475 .I flags
476 is invalid.
477 .SH STANDARDS
478 Linux.
479 .SH HISTORY
480 Linux 2.6.25,
481 glibc 2.8.
482 .SH NOTES
483 Suppose the following scenario for
484 .B CLOCK_REALTIME
485 or
486 .B CLOCK_REALTIME_ALARM
487 timer that was created with
488 .BR timerfd_create ():
489 .IP (1) 5
490 The timer has been started
491 .RB ( timerfd_settime ())
492 with the
493 .B TFD_TIMER_ABSTIME
494 and
495 .B TFD_TIMER_CANCEL_ON_SET
496 flags;
497 .IP (2)
498 A discontinuous change (e.g.,
499 .BR settimeofday (2))
500 is subsequently made to the
501 .B CLOCK_REALTIME
502 clock;
503 and
504 .IP (3)
505 the caller once more calls
506 .BR timerfd_settime ()
507 to rearm the timer (without first doing a
508 .BR read (2)
509 on the file descriptor).
510 .P
511 In this case the following occurs:
512 .IP \[bu] 3
513 The
514 .BR timerfd_settime ()
515 returns \-1 with
516 .I errno
517 set to
518 .BR ECANCELED .
519 (This enables the caller to know that the previous timer was affected
520 by a discontinuous change to the clock.)
521 .IP \[bu]
522 The timer
523 .I "is successfully rearmed"
524 with the settings provided in the second
525 .BR timerfd_settime ()
526 call.
527 (This was probably an implementation accident, but won't be fixed now,
528 in case there are applications that depend on this behavior.)
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).
535 .SH EXAMPLES
536 The following program creates a timer and then monitors its progress.
537 The program accepts up to three command-line arguments.
538 The first argument specifies the number of seconds for
539 the initial expiration of the timer.
540 The second argument specifies the interval for the timer, in seconds.
541 The third argument specifies the number of times the program should
542 allow the timer to expire before terminating.
543 The second and third command-line arguments are optional.
544 .P
545 The following shell session demonstrates the use of the program:
546 .P
547 .in +4n
548 .EX
549 .RB "$" " a.out 3 1 100"
550 0.000: timer started
551 3.000: read: 1; total=1
552 4.000: read: 1; total=2
553 .BR "\[ha]Z " " # type control\-Z to suspend the program"
554 [1]+ Stopped ./timerfd3_demo 3 1 100
555 .RB "$ " "fg" " # Resume execution after a few seconds"
556 a.out 3 1 100
557 9.660: read: 5; total=7
558 10.000: read: 1; total=8
559 11.000: read: 1; total=9
560 .BR "\[ha]C " " # type control\-C to suspend the program"
561 .EE
562 .in
563 .SS Program source
564 \&
565 .\" SRC BEGIN (timerfd_create.c)
566 .EX
567 .\" The commented out code here is what we currently need until
568 .\" the required stuff is in glibc
569 .\"
570 .\"
571 .\"/* Link with \-lrt */
572 .\"#define _GNU_SOURCE
573 .\"#include <sys/syscall.h>
574 .\"#include <unistd.h>
575 .\"#include <time.h>
576 .\"#if defined(__i386__)
577 .\"#define __NR_timerfd_create 322
578 .\"#define __NR_timerfd_settime 325
579 .\"#define __NR_timerfd_gettime 326
580 .\"#endif
581 .\"
582 .\"static int
583 .\"timerfd_create(int clockid, int flags)
584 .\"{
585 .\" return syscall(__NR_timerfd_create, clockid, flags);
586 .\"}
587 .\"
588 .\"static int
589 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
590 .\" struct itimerspec *curr_value)
591 .\"{
592 .\" return syscall(__NR_timerfd_settime, fd, flags, new_value,
593 .\" curr_value);
594 .\"}
595 .\"
596 .\"static int
597 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
598 .\"{
599 .\" return syscall(__NR_timerfd_gettime, fd, curr_value);
600 .\"}
601 .\"
602 .\"#define TFD_TIMER_ABSTIME (1 << 0)
603 .\"
604 .\"////////////////////////////////////////////////////////////
605 #include <err.h>
606 #include <inttypes.h>
607 #include <stdio.h>
608 #include <stdlib.h>
609 #include <sys/timerfd.h>
610 #include <sys/types.h>
611 #include <time.h>
612 #include <unistd.h>
613 \&
614 static void
615 print_elapsed_time(void)
616 {
617 int secs, nsecs;
618 static int first_call = 1;
619 struct timespec curr;
620 static struct timespec start;
621 \&
622 if (first_call) {
623 first_call = 0;
624 if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
625 err(EXIT_FAILURE, "clock_gettime");
626 }
627 \&
628 if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
629 err(EXIT_FAILURE, "clock_gettime");
630 \&
631 secs = curr.tv_sec \- start.tv_sec;
632 nsecs = curr.tv_nsec \- start.tv_nsec;
633 if (nsecs < 0) {
634 secs\-\-;
635 nsecs += 1000000000;
636 }
637 printf("%d.%03d:\[rs]t", secs, (nsecs + 500000) / 1000000);
638 }
639 \&
640 int
641 main(int argc, char *argv[])
642 {
643 int fd;
644 ssize_t s;
645 uint64_t expir, tot_expir, max_expir;
646 struct timespec now;
647 struct itimerspec new_value;
648 \&
649 if (argc != 2 && argc != 4) {
650 fprintf(stderr, "%s init\-secs [interval\-secs max\-num\-expir]\[rs]n",
651 argv[0]);
652 exit(EXIT_FAILURE);
653 }
654 \&
655 if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
656 err(EXIT_FAILURE, "clock_gettime");
657 \&
658 /* Create a CLOCK_REALTIME absolute timer with initial
659 expiration and interval as specified in command line. */
660 \&
661 new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
662 new_value.it_value.tv_nsec = now.tv_nsec;
663 if (argc == 2) {
664 new_value.it_interval.tv_sec = 0;
665 max_expir = 1;
666 } else {
667 new_value.it_interval.tv_sec = atoi(argv[2]);
668 max_expir = atoi(argv[3]);
669 }
670 new_value.it_interval.tv_nsec = 0;
671 \&
672 fd = timerfd_create(CLOCK_REALTIME, 0);
673 if (fd == \-1)
674 err(EXIT_FAILURE, "timerfd_create");
675 \&
676 if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
677 err(EXIT_FAILURE, "timerfd_settime");
678 \&
679 print_elapsed_time();
680 printf("timer started\[rs]n");
681 \&
682 for (tot_expir = 0; tot_expir < max_expir;) {
683 s = read(fd, &expir, sizeof(uint64_t));
684 if (s != sizeof(uint64_t))
685 err(EXIT_FAILURE, "read");
686 \&
687 tot_expir += expir;
688 print_elapsed_time();
689 printf("read: %w64u; total=%w64u\[rs]n", expir, tot_expir);
690 }
691 \&
692 exit(EXIT_SUCCESS);
693 }
694 .EE
695 .\" SRC END
696 .SH SEE ALSO
697 .BR eventfd (2),
698 .BR poll (2),
699 .BR read (2),
700 .BR select (2),
701 .BR setitimer (2),
702 .BR signalfd (2),
703 .BR timer_create (2),
704 .BR timer_gettime (2),
705 .BR timer_settime (2),
706 .BR timespec (3),
707 .BR epoll (7),
708 .BR time (7)