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 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
42       Starting with Linux 2.6.27, the following values may be bitwise ORed in
43       flags to change the behavior of timerfd_create():
44
45       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
49       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
53       In  Linux  versions up to and including 2.6.26, flags must be specified
54       as zero.
55
56   timerfd_settime()
57       timerfd_settime() arms (starts) or disarms (stops) the  timer  referred
58       to by the file descriptor fd.
59
60       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
64           struct timespec {
65               time_t tv_sec;                /* Seconds */
66               long   tv_nsec;               /* Nanoseconds */
67           };
68
69           struct itimerspec {
70               struct timespec it_interval;  /* Interval for periodic timer */
71               struct timespec it_value;     /* Initial expiration */
72           };
73
74       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
79       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
85       The  flags  argument  is  either  0,  to   start   a   relative   timer
86       (new_value.it_value  specifies  a time relative to the current value of
87       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
92       If  the  old_value  argument is not NULL, then the itimerspec structure
93       that it points to is used to return the setting of the timer  that  was
94       current  at  the  time of the call; see the description of timerfd_get‐
95       time() following.
96
97   timerfd_gettime()
98       timerfd_gettime() returns, in curr_value, an itimerspec structure  that
99       contains  the  current  setting  of  the  timer referred to by the file
100       descriptor fd.
101
102       The it_value field returns the amount of time until the timer will next
103       expire.   If  both fields of this structure are zero, then the timer is
104       currently disarmed.  This  field  always  contains  a  relative  value,
105       regardless  of  whether  the  TFD_TIMER_ABSTIME flag was specified when
106       setting the timer.
107
108       The it_interval field returns the  interval  of  the  timer.   If  both
109       fields of this structure are zero, then the timer is set to expire just
110       once, at the time specified by curr_value.it_value.
111
112   Operating on a timer file descriptor
113       The file descriptor returned by timerfd_create() supports the following
114       operations:
115
116       read(2)
117              If  the  timer  has  already expired one or more times since its
118              settings were last modified using  timerfd_settime(),  or  since
119              the  last  successful  read(2), then the buffer given to read(2)
120              returns an unsigned 8-byte  integer  (uint64_t)  containing  the
121              number  of  expirations that have occurred.  (The returned value
122              is in host byte order, i.e., the native byte order for  integers
123              on the host machine.)
124
125              If  no  timer  expirations  have  occurred  at  the  time of the
126              read(2), then the call either blocks until the next timer  expi‐
127              ration,  or  fails  with the error EAGAIN if the file descriptor
128              has been made nonblocking (via the use of the  fcntl(2)  F_SETFL
129              operation to set the O_NONBLOCK flag).
130
131              A  read(2)  will  fail  with the error EINVAL if the size of the
132              supplied buffer is less than 8 bytes.
133
134       poll(2), select(2) (and similar)
135              The file descriptor is readable (the select(2) readfds argument;
136              the  poll(2)  POLLIN flag) if one or more timer expirations have
137              occurred.
138
139              The file descriptor also supports the other file-descriptor mul‐
140              tiplexing APIs: pselect(2), ppoll(2), and epoll(7).
141
142       close(2)
143              When  the  file  descriptor  is  no longer required it should be
144              closed.  When all file  descriptors  associated  with  the  same
145              timer  object  have  been  closed, the timer is disarmed and its
146              resources are freed by the kernel.
147
148   fork(2) semantics
149       After a fork(2), the child inherits a copy of the file descriptor  cre‐
150       ated  by  timerfd_create().   The  file  descriptor  refers to the same
151       underlying timer object as the corresponding  file  descriptor  in  the
152       parent, and read(2)s in the child will return information about expira‐
153       tions of the timer.
154
155   execve(2) semantics
156       A file descriptor  created  by  timerfd_create()  is  preserved  across
157       execve(2), and continues to generate timer expirations if the timer was
158       armed.
159

RETURN VALUE

161       On success, timerfd_create() returns a new file descriptor.  On  error,
162       -1 is returned and errno is set to indicate the error.
163
164       timerfd_settime()  and  timerfd_gettime() return 0 on success; on error
165       they return -1, and set errno to indicate the error.
166

ERRORS

168       timerfd_create() can fail with the following errors:
169
170       EINVAL The clockid argument is neither CLOCK_MONOTONIC nor  CLOCK_REAL‐
171              TIME;
172
173       EINVAL flags  is  invalid;  or,  in  Linux  2.6.26 or earlier, flags is
174              nonzero.
175
176       EMFILE The per-process limit of open file descriptors has been reached.
177
178       ENFILE The system-wide limit on the total number of open files has been
179              reached.
180
181       ENODEV Could not mount (internal) anonymous inode device.
182
183       ENOMEM There was insufficient kernel memory to create the timer.
184
185       timerfd_settime()  and  timerfd_gettime()  can  fail with the following
186       errors:
187
188       EBADF  fd is not a valid file descriptor.
189
190       EFAULT new_value, old_value, or curr_value is not valid a pointer.
191
192       EINVAL fd is not a valid timerfd file descriptor.
193
194       timerfd_settime() can also fail with the following errors:
195
196       EINVAL new_value is not properly initialized (one of the tv_nsec  falls
197              outside the range zero to 999,999,999).
198
199       EINVAL flags is invalid.
200

VERSIONS

202       These system calls are available on Linux since kernel 2.6.25.  Library
203       support is provided by glibc since version 2.8.
204

CONFORMING TO

206       These system calls are Linux-specific.
207

BUGS

209       Currently, timerfd_create() supports fewer  types  of  clock  IDs  than
210       timer_create(2).
211

EXAMPLE

213       The  following  program creates a timer and then monitors its progress.
214       The program accepts up to  three  command-line  arguments.   The  first
215       argument  specifies the number of seconds for the initial expiration of
216       the timer.  The second argument specifies the interval for  the  timer,
217       in  seconds.  The third argument specifies the number of times the pro‐
218       gram should allow the timer to expire before terminating.   The  second
219       and third command-line arguments are optional.
220
221       The following shell session demonstrates the use of the program:
222
223           $ a.out 3 1 100
224           0.000: timer started
225           3.000: read: 1; total=1
226           4.000: read: 1; total=2
227           ^Z                  # type control-Z to suspend the program
228           [1]+  Stopped                 ./timerfd3_demo 3 1 100
229           $ fg                # Resume execution after a few seconds
230           a.out 3 1 100
231           9.660: read: 5; total=7
232           10.000: read: 1; total=8
233           11.000: read: 1; total=9
234           ^C                  # type control-C to suspend the program
235
236   Program source
237
238       #include <sys/timerfd.h>
239       #include <time.h>
240       #include <unistd.h>
241       #include <stdlib.h>
242       #include <stdio.h>
243       #include <stdint.h>        /* Definition of uint64_t */
244
245       #define handle_error(msg) \
246               do { perror(msg); exit(EXIT_FAILURE); } while (0)
247
248       static void
249       print_elapsed_time(void)
250       {
251           static struct timespec start;
252           struct timespec curr;
253           static int first_call = 1;
254           int secs, nsecs;
255
256           if (first_call) {
257               first_call = 0;
258               if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
259                   handle_error("clock_gettime");
260           }
261
262           if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
263               handle_error("clock_gettime");
264
265           secs = curr.tv_sec - start.tv_sec;
266           nsecs = curr.tv_nsec - start.tv_nsec;
267           if (nsecs < 0) {
268               secs--;
269               nsecs += 1000000000;
270           }
271           printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
272       }
273
274       int
275       main(int argc, char *argv[])
276       {
277           struct itimerspec new_value;
278           int max_exp, fd;
279           struct timespec now;
280           uint64_t exp, tot_exp;
281           ssize_t s;
282
283           if ((argc != 2) && (argc != 4)) {
284               fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",
285                       argv[0]);
286               exit(EXIT_FAILURE);
287           }
288
289           if (clock_gettime(CLOCK_REALTIME, &now) == -1)
290               handle_error("clock_gettime");
291
292           /* Create a CLOCK_REALTIME absolute timer with initial
293              expiration and interval as specified in command line */
294
295           new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
296           new_value.it_value.tv_nsec = now.tv_nsec;
297           if (argc == 2) {
298               new_value.it_interval.tv_sec = 0;
299               max_exp = 1;
300           } else {
301               new_value.it_interval.tv_sec = atoi(argv[2]);
302               max_exp = atoi(argv[3]);
303           }
304           new_value.it_interval.tv_nsec = 0;
305
306           fd = timerfd_create(CLOCK_REALTIME, 0);
307           if (fd == -1)
308               handle_error("timerfd_create");
309
310           if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
311               handle_error("timerfd_settime");
312
313           print_elapsed_time();
314           printf("timer started\n");
315
316           for (tot_exp = 0; tot_exp < max_exp;) {
317               s = read(fd, &exp, sizeof(uint64_t));
318               if (s != sizeof(uint64_t))
319                   handle_error("read");
320
321               tot_exp += exp;
322               print_elapsed_time();
323               printf("read: %llu; total=%llu\n",
324                       (unsigned long long) exp,
325                       (unsigned long long) tot_exp);
326           }
327
328           exit(EXIT_SUCCESS);
329       }
330

SEE ALSO

332       eventfd(2),  poll(2),  read(2),  select(2),  setitimer(2), signalfd(2),
333       timer_create(2), timer_gettime(2), timer_settime(2), epoll(7), time(7)
334

COLOPHON

336       This page is part of release 3.53 of the Linux  man-pages  project.   A
337       description  of  the project, and information about reporting bugs, can
338       be found at http://www.kernel.org/doc/man-pages/.
339
340
341
342Linux                             2011-09-14                 TIMERFD_CREATE(2)
Impressum