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