original/man2/timerfd_create.2

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