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