1TIMERFD_CREATE(2)          Linux Programmer's Manual         TIMERFD_CREATE(2)
2
3
4

NAME

6       timerfd_create,  timerfd_settime,  timerfd_gettime - timers that notify
7       via file descriptors
8

SYNOPSIS

10       #include <sys/timerfd.h>
11
12       int timerfd_create(int clockid, int flags);
13
14       int timerfd_settime(int fd, int flags,
15                           const struct itimerspec *new_value,
16                           struct itimerspec *old_value);
17
18       int timerfd_gettime(int fd, struct itimerspec *curr_value);
19

DESCRIPTION

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
27       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
32   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
38       CLOCK_REALTIME
39              A settable system-wide real-time clock.
40
41       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
46       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
55       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
60       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
65       The current value of each  of  these  clocks  can  be  retrieved  using
66       clock_gettime(2).
67
68       Starting with Linux 2.6.27, the following values may be bitwise ORed in
69       flags to change the behavior of timerfd_create():
70
71       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
75       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
79       In Linux versions up to and including 2.6.26, flags must  be  specified
80       as zero.
81
82   timerfd_settime()
83       timerfd_settime()  arms  (starts) or disarms (stops) the timer referred
84       to by the file descriptor fd.
85
86       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
91           struct timespec {
92               time_t tv_sec;                /* Seconds */
93               long   tv_nsec;               /* Nanoseconds */
94           };
95
96           struct itimerspec {
97               struct timespec it_interval;  /* Interval for periodic timer */
98               struct timespec it_value;     /* Initial expiration */
99           };
100
101       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
106       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
112       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
118       The flags argument is a bit mask that can include the following values:
119
120       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
125       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
134       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
139   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
144       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
150       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
154   Operating on a timer file descriptor
155       The file descriptor returned by timerfd_create() supports the following
156       operations:
157
158       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
167              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
173              A read(2) fails with the error EINVAL if the size  of  the  sup‐
174              plied buffer is less than 8 bytes.
175
176              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
184       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
189              The file descriptor also supports the other file-descriptor mul‐
190              tiplexing APIs: pselect(2), ppoll(2), and epoll(7).
191
192       ioctl(2)
193              The following timerfd-specific command is supported:
194
195              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
206       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
212   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
219   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

RETURN VALUE

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
228       timerfd_settime() and timerfd_gettime() return 0 on success;  on  error
229       they return -1, and set errno to indicate the error.
230

ERRORS

232       timerfd_create() can fail with the following errors:
233
234       EINVAL The  clockid argument is neither CLOCK_MONOTONIC nor CLOCK_REAL‐
235              TIME;
236
237       EINVAL flags is invalid; or, in  Linux  2.6.26  or  earlier,  flags  is
238              nonzero.
239
240       EMFILE The per-process limit on the number of open file descriptors has
241              been reached.
242
243       ENFILE The system-wide limit on the total number of open files has been
244              reached.
245
246       ENODEV Could not mount (internal) anonymous inode device.
247
248       ENOMEM There was insufficient kernel memory to create the timer.
249
250       timerfd_settime()  and  timerfd_gettime()  can  fail with the following
251       errors:
252
253       EBADF  fd is not a valid file descriptor.
254
255       EFAULT new_value, old_value, or curr_value is not valid a pointer.
256
257       EINVAL fd is not a valid timerfd file descriptor.
258
259       timerfd_settime() can also fail with the following errors:
260
261       EINVAL new_value is not properly initialized (one of the tv_nsec  falls
262              outside the range zero to 999,999,999).
263
264       EINVAL flags is invalid.
265

VERSIONS

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

CONFORMING TO

271       These system calls are Linux-specific.
272

BUGS

274       Currently, timerfd_create() supports fewer  types  of  clock  IDs  than
275       timer_create(2).
276

EXAMPLE

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
286       The following shell session demonstrates the use of the program:
287
288           $ 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
301   Program source
302
303       #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
310       #define handle_error(msg) \
311               do { perror(msg); exit(EXIT_FAILURE); } while (0)
312
313       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
321           if (first_call) {
322               first_call = 0;
323               if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
324                   handle_error("clock_gettime");
325           }
326
327           if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
328               handle_error("clock_gettime");
329
330           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
339       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
348           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
354           if (clock_gettime(CLOCK_REALTIME, &now) == -1)
355               handle_error("clock_gettime");
356
357           /* Create a CLOCK_REALTIME absolute timer with initial
358              expiration and interval as specified in command line */
359
360           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
371           fd = timerfd_create(CLOCK_REALTIME, 0);
372           if (fd == -1)
373               handle_error("timerfd_create");
374
375           if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
376               handle_error("timerfd_settime");
377
378           print_elapsed_time();
379           printf("timer started\n");
380
381           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
386               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
393           exit(EXIT_SUCCESS);
394       }
395

SEE ALSO

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

COLOPHON

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/.
405
406
407
408Linux                             2017-09-15                 TIMERFD_CREATE(2)
Impressum