man2/timerfd_create.2

   1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" This program is free software; you can redistribute it and/or modify
   4 .\" it under the terms of the GNU General Public License as published by
   5 .\" the Free Software Foundation; either version 2 of the License, or
   6 .\" (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 .\" GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program; if not, write to the Free Software
  15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  16 .\" MA  02111-1307  USA
  17 .\"
  18 .TH TIMERFD_CREATE 2 2008-02-22 Linux "Linux Programmer's Manual"
  19 .SH NAME
  20 timerfd_create, timerfd_settime, timerfd_gettime \-
  21 timers that notify via file descriptors
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <sys/timerfd.h>
  25 .sp
  26 .BI "int timerfd_create(int " clockid ", int " flags );
  27 .sp
  28 .BI "int timerfd_settime(int " fd ", int " flags ,
  29 .BI "                    const struct itimerspec *" new_value ,
  30 .BI "                    struct itimerspec *" curr_value );
  31 .sp
  32 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
  33 .fi
  34 .SH DESCRIPTION
  35 These system calls create and operate on a timer
  36 that delivers timer expiration notifications via a file descriptor.
  37 They provide an alternative to the use of
  38 .BR setitimer (2)
  39 or
  40 .BR timer_create (3),
  41 with the advantage that the file descriptor may be monitored by
  42 .BR select (2),
  43 .BR poll (2),
  44 and
  45 .BR epoll (7).
  46
  47 The use of these three system calls is analogous to the use of
  48 .BR timer_create (3),
  49 .BR timer_settime (3),
  50 and
  51 .BR timer_gettime (3).
  52 (There is no analog of
  53 .BR timer_gettoverrun (3),
  54 since that functionality is provided by
  55 .BR read (2),
  56 as described below.)
  57 .\"
  58 .SS timerfd_create()
  59 .BR timerfd_create ()
  60 creates a new timer object,
  61 and returns a file descriptor that refers to that timer.
  62 The
  63 .I clockid
  64 argument specifies the clock that is used to mark the progress
  65 of the timer, and must be either
  66 .B CLOCK_REALTIME
  67 or
  68 .BR CLOCK_MONOTONIC .
  69 .B CLOCK_REALTIME
  70 is a settable system-wide clock.
  71 .B CLOCK_MONOTONIC
  72 is a non-settable clock that is not affected
  73 by discontinuous changes in the system clock
  74 (e.g., manual changes to system time).
  75 The current value of each of these clocks can be retrieved using
  76 .BR clock_gettime (3).
  77
  78 The
  79 .I flags
  80 argument is reserved for future use.
  81 .\" Eventually it will probably allow O_CLOEXEC and maybe O_NONBLOCK.
  82 As at Linux 2.6.25, this argument must be specified as zero.
  83 .\"
  84 .SS timerfd_settime()
  85 .BR timerfd_settime ()
  86 arms (starts) or disarms (stops)
  87 the timer referred to by the file descriptor
  88 .IR fd .
  89
  90 The
  91 .I new_value
  92 argument specifies the initial expiration and interval for the timer.
  93 The
  94 .I itimer
  95 structure used for this argument contains two fields,
  96 each of which is in turn a structure of type
  97 .IR timespec :
  98 .in +4n
  99 .nf
 100
 101 struct timespec {
 102     time_t tv_sec;                /* Seconds */
 103     long   tv_nsec;               /* Nanoseconds */
 104 };
 105
 106 struct itimerspec {
 107     struct timespec it_interval;  /* Interval for periodic timer */
 108     struct timespec it_value;     /* Initial expiration */
 109 };
 110 .fi
 111 .in
 112 .PP
 113 .I new_value.it_value
 114 specifies the initial expiration of the timer,
 115 in seconds and nanoseconds.
 116 Setting either field of
 117 .I new_value.it_value
 118 to a non-zero value arms the timer.
 119 Setting both fields of
 120 .I new_value.it_value
 121 to zero disarms the timer.
 122
 123 Setting one or both fields of
 124 .I new_value.it_interval
 125 to non-zero values specifies the period, in seconds and nanoseconds,
 126 for repeated timer expirations after the initial expiration.
 127 If both fields of
 128 .I new_value.it_interval
 129 are zero, the timer expires just once, at the time specified by
 130 .IR new_value.it_value .
 131
 132 The
 133 .I flags
 134 argument is either 0, to start a relative timer
 135 .RI ( new_value.it_interval
 136 specifies a time relative to the current value of the clock specified by
 137 .IR clockid ),
 138 or
 139 .BR TFD_TIMER_ABSTIME ,
 140 to start an absolute timer
 141 .RI ( new_value.it_interval
 142 specifies an absolute time for the clock specified by
 143 .IR clockid ;
 144 that is, the timer will expire when the value of that
 145 clock reaches the value specified in
 146 .IR new_value.it_interval ).
 147
 148 The
 149 .I curr_value
 150 argument returns a structure containing the setting of the timer that
 151 was current at the time of the call; see the description of
 152 .BR timerfd_gettime ()
 153 following.
 154 .\"
 155 .SS timerfd_gettime()
 156 .BR timerfd_gettime ()
 157 returns, in
 158 .IR curr_value ,
 159 an
 160 .IR itimerspec
 161 that contains the current setting of the timer
 162 referred to by the file descriptor
 163 .IR fd .
 164
 165 The
 166 .I it_value
 167 field returns the amount of time
 168 until the timer will next expire.
 169 If both fields of this structure are zero,
 170 then the timer is currently disarmed.
 171 This field always contains a relative value, regardless of whether the
 172 .BR TFD_TIMER_ABSTIME
 173 flag was specified when setting the timer.
 174
 175 The
 176 .I it_interval
 177 field returns the interval of the timer.
 178 If both fields of this structure are zero,
 179 then the timer is set to expire just once, at the time specified by
 180 .IR curr_value.it_value .
 181 .SS Operating on a timer file descriptor
 182 The file descriptor returned by
 183 .BR timerfd_create ()
 184 supports the following operations:
 185 .TP
 186 .BR read (2)
 187 If the timer has already expired one or more times since
 188 its settings were last modified using
 189 .BR timerfd_settime (),
 190 or since the last successful
 191 .BR read (2),
 192 then the buffer given to
 193 .BR read (2)
 194 returns an unsigned 8-byte integer
 195 .RI ( uint64_t )
 196 containing the number of expirations that have occurred.
 197 (The returned value is in host byte order,
 198 i.e., the native byte order for integers on the host machine.)
 199 .IP
 200 If no timer expirations have occurred at the time of the
 201 .BR read (2),
 202 then the call either blocks until the next timer expiration,
 203 or fails with the error
 204 .B EAGAIN
 205 if the file descriptor has been made non-blocking
 206 (via the use of the
 207 .BR fcntl (2)
 208 .B F_SETFL
 209 operation to set the
 210 .B O_NONBLOCK
 211 flag).
 212 .IP
 213 A
 214 .BR read (2)
 215 will fail with the error
 216 .B EINVAL
 217 if the size of the supplied buffer is less than 8 bytes.
 218 .TP
 219 .BR poll "(2), " select "(2) (and similar)"
 220 The file descriptor is readable
 221 (the
 222 .BR select (2)
 223 .I readfds
 224 argument; the
 225 .BR poll (2)
 226 .B POLLIN
 227 flag)
 228 if one or more timer expirations have occurred.
 229 .IP
 230 The file descriptor also supports the other file-descriptor
 231 multiplexing APIs:
 232 .BR pselect (2),
 233 .BR ppoll (2),
 234 and
 235 .BR epoll (7).
 236 .TP
 237 .BR close (2)
 238 When the file descriptor is no longer required it should be closed.
 239 When all file descriptors associated with the same timer object
 240 have been closed,
 241 the timer is disarmed and its resources are freed by the kernel.
 242 .\"
 243 .SS fork(2) semantics
 244 After a
 245 .BR fork (2),
 246 the child inherits a copy of the file descriptor created by
 247 .BR timerfd_create ().
 248 The file descriptor refers to the same underlying
 249 timer object as the corresponding file descriptor in the parent,
 250 and
 251 .BR read (2)s
 252 in the child will return information about
 253 expirations of the timer.
 254 .\"
 255 .SS execve(2) semantics
 256 A file descriptor created by
 257 .BR timerfd_create ()
 258 is preserved across
 259 .BR execve (2),
 260 and continues to generate timer expirations if the timer was armed.
 261 .SH "RETURN VALUE"
 262 On success,
 263 .BR timerfd_create ()
 264 returns a new file descriptor.
 265 On error, \-1 is returned and
 266 .I errno
 267 is set to indicate the error.
 268
 269 .BR timerfd_settime ()
 270 and
 271 .BR timerfd_gettime ()
 272 return 0 on success;
 273 on error they return \-1, and set
 274 .I errno
 275 to indicate the error.
 276 .SH ERRORS
 277 .BR timerfd_create ()
 278 can fail with the following errors:
 279 .TP
 280 .B EINVAL
 281 The
 282 .I clockid
 283 argument is neither
 284 .B CLOCK_MONOTONIC
 285 nor
 286 .BR CLOCK_REALTIME ;
 287 or
 288 .I flags
 289 is invalid.
 290 .TP
 291 .B EMFILE
 292 The per-process limit of open file descriptors has been reached.
 293 .TP
 294 .B ENFILE
 295 The system-wide limit on the total number of open files has been
 296 reached.
 297 .TP
 298 .B ENODEV
 299 Could not mount (internal) anonymous inode device.
 300 .TP
 301 .B ENOMEM
 302 There was insufficient kernel memory to create the timer.
 303 .PP
 304 .BR timerfd_settime ()
 305 and
 306 .BR timerfd_gettime ()
 307 can fail with the following errors:
 308 .TP
 309 .B EBADF
 310 .I fd
 311 is not a valid file descriptor.
 312 .TP
 313 .B EINVAL
 314 .I fd
 315 is not a valid timerfd file descriptor.
 316 .I new_value
 317 is not properly initialized (one of the
 318 .I tv_nsec
 319 falls outside the range zero to 999,999,999).
 320 .SH VERSIONS
 321 These system calls are available on Linux since kernel 2.6.25.
 322 Library support is provided by in glibc since version 2.8.
 323 .SH CONFORMING TO
 324 These system calls are Linux-specific.
 325 .SH EXAMPLE
 326 The following program creates a timer and then monitors its progress.
 327 The program accepts up to three command-line arguments.
 328 The first argument specifies the number of seconds for
 329 the initial expiration of the timer.
 330 The second argument specifies the interval for the timer, in seconds.
 331 The third argument specifies the number of times the program should
 332 allow the timer to expire before terminating.
 333 The second and third command-line arguments are optional.
 334
 335 The following shell session demonstrates the use of the program:
 336 .in +4n
 337 .nf
 338
 339 $ a.out 3 1 100
 340 0.000: timer started
 341 3.000: read: 1; total=1
 342 4.000: read: 1; total=2
 343 [type control-Z to suspend the program]
 344 [1]+  Stopped                 ./timerfd3_demo 3 1 100
 345 $ fg                # Resume execution after a few seconds
 346 a.out 3 1 100
 347 9.660: read: 5; total=7
 348 10.000: read: 1; total=8
 349 11.000: read: 1; total=9
 350 [type control-C to terminate the program]
 351 .fi
 352 .in
 353 .nf
 354
 355 .\" The commented out code here is what we currently need until
 356 .\" the required stuff is in glibc
 357 .\"
 358 .\"
 359 .\"/* Link with -lrt */
 360 .\"#define _GNU_SOURCE
 361 .\"#include <sys/syscall.h>
 362 .\"#include <unistd.h>
 363 .\"#include <time.h>
 364 .\"#if defined(__i386__)
 365 .\"#define __NR_timerfd_create 322
 366 .\"#define __NR_timerfd_settime 325
 367 .\"#define __NR_timerfd_gettime 326
 368 .\"#endif
 369 .\"
 370 .\"static int
 371 .\"timerfd_create(int clockid, int flags)
 372 .\"{
 373 .\"    return syscall(__NR_timerfd_create, clockid, flags);
 374 .\"}
 375 .\"
 376 .\"static int
 377 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
 378 .\"        struct itimerspec *curr_value)
 379 .\"{
 380 .\"    return syscall(__NR_timerfd_settime, fd, flags, new_value,
 381 .\"                   curr_value);
 382 .\"}
 383 .\"
 384 .\"static int
 385 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
 386 .\"{
 387 .\"    return syscall(__NR_timerfd_gettime, fd, curr_value);
 388 .\"}
 389 .\"
 390 .\"#define TFD_TIMER_ABSTIME (1 << 0)
 391 .\"
 392 .\"////////////////////////////////////////////////////////////
 393 #include <sys/timerfd.h>
 394 #include <time.h>
 395 #include <unistd.h>
 396 #include <stdlib.h>
 397 #include <stdio.h>
 398 #include <stdint.h>        /* Definition of uint64_t */
 399
 400 #define handle_error(msg) \\
 401         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 402
 403 static void
 404 print_elapsed_time(void)
 405 {
 406     static struct timespec start;
 407     struct timespec curr;
 408     static int first_call = 1;
 409     int secs, nsecs;
 410
 411     if (first_call) {
 412         first_call = 0;
 413         if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
 414             handle_error("clock_gettime");
 415     }
 416
 417     if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
 418         handle_error("clock_gettime");
 419
 420     secs = curr.tv_sec \- start.tv_sec;
 421     nsecs = curr.tv_nsec \- start.tv_nsec;
 422     if (nsecs < 0) {
 423         secs\-\-;
 424         nsecs += 1000000000;
 425     }
 426     printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
 427 }
 428
 429 int
 430 main(int argc, char *argv[])
 431 {
 432     struct itimerspec new_value;
 433     int max_exp, fd;
 434     struct timespec now;
 435     uint64_t exp, tot_exp;
 436     ssize_t s;
 437
 438     if ((argc != 2) && (argc != 4)) {
 439         fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n",
 440                 argv[0]);
 441         exit(EXIT_FAILURE);
 442     }
 443
 444     if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
 445         handle_error("clock_gettime");
 446
 447     /* Create a CLOCK_REALTIME absolute timer with initial
 448        expiration and interval as specified in command line */
 449
 450     new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
 451     new_value.it_value.tv_nsec = now.tv_nsec;
 452     if (argc == 2) {
 453         new_value.it_interval.tv_sec = 0;
 454         max_exp = 1;
 455     } else {
 456         new_value.it_interval.tv_sec = atoi(argv[2]);
 457         max_exp = atoi(argv[3]);
 458     }
 459     new_value.it_interval.tv_nsec = 0;
 460
 461     fd = timerfd_create(CLOCK_REALTIME, 0);
 462     if (fd == \-1)
 463         handle_error("timerfd_create");
 464
 465     s = timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL);
 466     if (s == \-1)
 467         handle_error("timerfd_settime");
 468
 469     print_elapsed_time();
 470     printf("timer started\\n");
 471
 472     for (tot_exp = 0; tot_exp < max_exp;) {
 473         s = read(fd, &exp, sizeof(uint64_t));
 474         if (s != sizeof(uint64_t))
 475             handle_error("read");
 476
 477         tot_exp += exp;
 478         print_elapsed_time();
 479         printf("read: %llu; total=%llu\\n",
 480                 (unsigned long long) exp,
 481                 (unsigned long long) tot_exp);
 482     }
 483
 484     exit(EXIT_SUCCESS);
 485 }
 486 .fi
 487 .SH "SEE ALSO"
 488 .BR eventfd (2),
 489 .BR poll (2),
 490 .BR read (2),
 491 .BR select (2),
 492 .BR setitimer (2),
 493 .BR signalfd (2),
 494 .BR timer_create (3),
 495 .BR timer_gettime (3),
 496 .BR timer_settime (3),
 497 .BR epoll (7),
 498 .BR time (7)