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