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 non-settable 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   non-zero   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 non-zero  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_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
92       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
96   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
101       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
107       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
111   Operating on a timer file descriptor
112       The file descriptor returned by timerfd_create() supports the following
113       operations:
114
115       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
124              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 non-blocking (via the use of the fcntl(2) F_SETFL
128              operation to set the O_NONBLOCK flag).
129
130              A read(2) will fail with the error EINVAL if  the  size  of  the
131              supplied buffer is less than 8 bytes.
132
133       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
138              The file descriptor also supports the other file-descriptor mul‐
139              tiplexing APIs: pselect(2), ppoll(2), and epoll(7).
140
141       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
147   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
154   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

RETURN VALUE

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

ERRORS

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

VERSIONS

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

CONFORMING TO

205       These system calls are Linux-specific.
206

EXAMPLE

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
216       The following shell session demonstrates the use of the program:
217
218           $ 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
231   Program source
232
233       #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
240       #define handle_error(msg) \
241               do { perror(msg); exit(EXIT_FAILURE); } while (0)
242
243       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
251           if (first_call) {
252               first_call = 0;
253               if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)
254                   handle_error("clock_gettime");
255           }
256
257           if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)
258               handle_error("clock_gettime");
259
260           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
269       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
278           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
284           if (clock_gettime(CLOCK_REALTIME, &now) == -1)
285               handle_error("clock_gettime");
286
287           /* Create a CLOCK_REALTIME absolute timer with initial
288              expiration and interval as specified in command line */
289
290           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
301           fd = timerfd_create(CLOCK_REALTIME, 0);
302           if (fd == -1)
303               handle_error("timerfd_create");
304
305           if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)
306               handle_error("timerfd_settime");
307
308           print_elapsed_time();
309           printf("timer started\n");
310
311           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
316               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
323           exit(EXIT_SUCCESS);
324       }
325

BUGS

327       Currently,  timerfd_create()  supports  fewer  types  of clock IDs than
328       timer_create(2).
329

SEE ALSO

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

COLOPHON

335       This  page  is  part of release 3.22 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/.
338
339
340
341Linux                             2009-03-10                 TIMERFD_CREATE(2)
Impressum