release/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 .\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
  19 .\"         all rights reserved.
  20 .\" Translated 2008-11-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.13
  21 .\" Updated 2009-04-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP 3.20
  22 .\"
  23 .TH TIMERFD_CREATE 2 2009-03-10 Linux "Linux Programmer's Manual"
  24 .SH 名前
  25 timerfd_create, timerfd_settime, timerfd_gettime \-
  26 ファイルディスクリプタ経由で通知するタイマー
  27 .SH 書式
  28 .nf
  29 .B #include <sys/timerfd.h>
  30 .sp
  31 .BI "int timerfd_create(int " clockid ", int " flags );
  32 .sp
  33 .BI "int timerfd_settime(int " fd ", int " flags ,
  34 .BI "                    const struct itimerspec *" new_value ,
  35 .BI "                    struct itimerspec *" old_value );
  36 .sp
  37 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
  38 .fi
  39 .SH 説明
  40 これらのシステムコールは、満了通知をファイルディスクリプタ経由で配送する
  41 タイマーの生成と操作を行う。
  42 これらは、
  43 .BR setitimer (2)
  44 や
  45 .BR timer_create (2)
  46 を用いる方法の代わりとなるものであり、このファイルディスクリプタを
  47 .BR select (2),
  48 .BR poll (2),
  49 .BR epoll (7)
  50 で監視できるという利点がある。
  51
  52 これらのシステムコールを使うのは、それぞれ
  53 .BR timer_create (2),
  54 .BR timer_settime (2),
  55 .BR timer_gettime (2)
  56 を使うのと同様である
  57 .RB ( timer_getoverrun (2)
  58 に対応するものはなく、以下で説明するように
  59 この機能は
  60 .BR read (2)
  61 により提供される)。
  62 .\"
  63 .SS timerfd_create()
  64 .BR timerfd_create ()
  65 は新規のタイマーオブジェクトを生成し、そのタイマーを参照するファイル
  66 ディスクリプタを返す。
  67 .I clockid
  68 引き数は、タイマーの進捗を管理するためのクロックを指定するもので、
  69 .B CLOCK_REALTIME
  70 か
  71 .B CLOCK_MONOTONIC
  72 のいずれかでなければならない。
  73 .B CLOCK_REALTIME
  74 はシステム全体で使用されるクロックで、このクロックは変更可能である。
  75 .B CLOCK_MONOTONIC
  76 は変更されることのないクロックで、(システム時刻の手動での変更などの)
  77 システムクロックの不連続な変化の影響を受けない。
  78 これらのクロックの現在の値は
  79 .BR clock_gettime (2)
  80 を使って取得できる。
  81
  82 Linux 2.6.27 以降では、
  83 以下の値のいくつかをビット単位の論理和 (OR) で指定することで、
  84 .BR timerfd_create ()
  85 の振舞いを変更することができる。
  86 .TP 14
  87 .B TFD_NONBLOCK
  88 新しく生成されるオープンファイル記述 (open file description) の
  89 .B O_NONBLOCK
  90 ファイルステータスフラグをセットする。
  91 このフラグを使うことで、
  92 .B O_NONBLOCK
  93 をセットするために
  94 .BR fcntl (2)
  95 を追加で呼び出す必要がなくなる。
  96 .TP
  97 .B TFD_CLOEXEC
  98 新しいファイルディスクリプタに対して
  99 close-on-exec
 100 .RB ( FD_CLOEXEC )
 101 フラグをセットする。
 102 このフラグが役に立つ理由については、
 103 .BR open (2)
 104 の
 105 .B O_CLOEXEC
 106 フラグの説明を参照のこと。
 107 .PP
 108 バージョン 2.6.26 以前の Linux では、
 109 .I flags
 110 引き数は未使用であり、0 を指定しなければならない。
 111 .SS timerfd_settime()
 112 .BR timerfd_settime ()
 113 は、ファイルディスクリプタ
 114 .I fd
 115 により参照されるタイマーを開始したり停止したりする。
 116
 117 .I new_value
 118 引き数は、タイマーの満了時間 (expiration) の初期値と間隔 (interval) を
 119 指定する。この引き数で使用されている
 120 .I itimerspec
 121 構造体には 2 つのフィールドがあり、各フィールドは
 122 .I timespec
 123 型の構造体である。
 124 .in +4n
 125 .nf
 126
 127 struct timespec {
 128     time_t tv_sec;                /* Seconds */
 129     long   tv_nsec;               /* Nanoseconds */
 130 };
 131
 132 struct itimerspec {
 133     struct timespec it_interval;  /* Interval for periodic timer */
 134     struct timespec it_value;     /* Initial expiration */
 135 };
 136 .fi
 137 .in
 138 .PP
 139 .I new_value.it_value
 140 はタイマーの満了時間の初期値を、秒とナノ秒で指定する。
 141 .I new_value.it_value
 142 のフィールドのうち少なくとも一方に 0 以外の値を設定すると、
 143 タイマーが開始される。
 144 両方のフィールドに 0 を設定すると、タイマーが停止する。
 145
 146 .I new_value.it_interval
 147 はタイマーの一回目の満了後に繰り返しタイマーの満了間隔を、秒とナノ秒で指定する。
 148 .I new_value.it_interval
 149 のフィールドのうち少なくとも一方に 0 以外の値を設定すると、
 150 繰り返しタイマーが有効になる。
 151 両方のフィールドに 0 を設定した場合、タイマーは
 152 .I new_value.it_value
 153 で指定された時間後に、一回だけ満了して停止する。
 154
 155 .I flags
 156 引き数には 0 か
 157 .B TFD_TIMER_ABSTIME
 158 を指定する。
 159 0 は相対時刻タイマーを意味し、
 160 .I new_value.it_interval
 161 では
 162 .I clockid
 163 で指定されたクロックの現在の値からの相対的な時刻を指定する。
 164 .B TFD_TIMER_ABSTIME
 165 は絶対時刻タイマーを意味し、
 166 .I new_value.it_interval
 167 では
 168 .I clockid
 169 で指定されたクロックの絶対時刻を指定する。つまり、
 170 クロックの値が
 171 .I new_value.it_interval
 172 で指定された時刻に達したら、タイマーが満了する。
 173
 174 .I old_value
 175 引き数を通じて、
 176 .BR timerfd_settime ()
 177 を呼び出した時点でのタイマーの設定を保持した構造体が返される。
 178 下記の
 179 .BR timerfd_gettime ()
 180 の説明を参照。
 181 .\"
 182 .SS timerfd_gettime()
 183 .BR timerfd_gettime ()
 184 は、ファイルディスクリプタ
 185 .I fd
 186 で参照されるタイマーの現在の設定が入った
 187 .I itimerspec
 188 構造体を、
 189 .I curr_value
 190 に格納して返す。
 191
 192 .I it_value
 193 フィールドは、タイマーが次に満了するまでの残り時間を返す。
 194 この構造体の両方のフィールドが 0 であれば、タイマーは現在停止している。
 195 タイマー設定時に
 196 .B TFD_TIMER_ABSTIME
 197 フラグが指定されたかに関わらず、このフィールドは常に相対値が格納される。
 198
 199 .I it_interval
 200 フィールドは、タイマーの間隔を返す。
 201 この構造体の両方のフィールドが 0 であれば、タイマーは
 202 .I new_value.it_value
 203 で指定された時間後に一回だけ満了して停止するように設定されている。
 204 .SS タイマー・ファイルディスクリプタに対する操作
 205 .BR timerfd_create ()
 206 が返すファイルディスクリプタは以下の操作をサポートしている。
 207 .TP
 208 .BR read (2)
 209 .BR timerfd_settime ()
 210 を使ってタイマーの設定が最後変更されて以降、または
 211 .BR read (2)
 212 の呼び出しに最後に成功して以降に、タイマーの満了が一回以上発生していれば、
 213 .BR read (2)
 214 に渡されたバッファに、タイマー満了回数を示す 8 バイトの unsigned 型の整数
 215 .RI ( uint64_t )
 216 が返される
 217 (返される値はホストバイトオーダ、つまりそのホストマシンにおける
 218 整数の通常のバイトオーダである)。
 219 .IP
 220 .BR read (2)
 221 を行った時点でタイマーの満了が発生していなければ、
 222 .BR read (2)
 223 は停止 (block) する、もしくはファイルディスクリプタが
 224 非停止 (nonblocking) に設定されている場合はエラー
 225 .B EAGAIN
 226 で失敗する (非停止モードにするには、
 227 .BR fcntl (2)
 228 の
 229 .B F_SETFL
 230 命令で
 231 .B O_NONBLOCK
 232 フラグをセットする)。
 233 .IP
 234 渡されたバッファのサイズが 8 バイト未満の場合、
 235 .BR read (2)
 236 はエラー
 237 .B EINVAL
 238 で失敗する。
 239 .TP
 240 .BR poll "(2), " select "(2) (と同様の操作)"
 241 一つ以上のタイマー満了が発生していれば、
 242 ファイルディスクリプタは読み出し可能となる
 243 .RB ( select (2)
 244 の
 245 .I readfds
 246 引き数や
 247 .BR poll (2)
 248 の
 249 .B POLLIN
 250 フラグ)。
 251 .IP
 252 このファイルディスクリプタは、他のファイルディスクリプタ多重 API である
 253 .BR pselect (2),
 254 .BR ppoll (2),
 255 .BR epoll (7)
 256 もサポートしている。
 257 .TP
 258 .BR close (2)
 259 ファイルディスクリプタがそれ以降は必要なくなった際には、クローズすべきである。
 260 同じ timer オブジェクトに関連付けられたファイルディスクリプタが全て
 261 クローズされると、そのタイマーは解除され、
 262 そのオブジェクト用の資源がカーネルにより解放される。
 263 .\"
 264 .SS fork(2) での扱い
 265 .BR fork (2)
 266 が行われると、子プロセスは
 267 .BR timerfd_create ()
 268 により生成されたファイルディスクリプタのコピーを
 269 継承する。そのファイルディスクリプタは、親プロセスの対応する
 270 ファイルディスクリプタと同じタイマーオブジェクトを参照しており、
 271 子プロセスの
 272 .BR read (2)
 273 でも同じタイマーの満了に関する情報が返される。
 274 .\"
 275 .SS execve(2) での扱い
 276 .BR execve (2)
 277 の前後で
 278 .BR timerfd_create ()
 279 により生成されたファイルディスクリプタは保持され、
 280 タイマーが開始されていた場合にはタイマーの満了が発生し続ける。
 281 .SH 返り値
 282 成功すると、
 283 .BR timerfd_create ()
 284 は新しいファイルディスクリプタを返す。
 285 エラーの場合、\-1 を返し、
 286 .I errno
 287 にエラーを示す値を設定する。
 288
 289 .BR timerfd_settime ()
 290 と
 291 .BR timerfd_gettime ()
 292 は成功すると 0 を返す。
 293 エラーの場合、\-1 を返し、
 294 .I errno
 295 にエラーを示す値を設定する。
 296 .SH エラー
 297 .BR timerfd_create ()
 298 は以下のエラーで失敗する可能性がある。
 299 .TP
 300 .B EINVAL
 301 .I clockid
 302 引き数が
 303 .B CLOCK_MONOTONIC
 304 でも
 305 .B CLOCK_REALTIME
 306 でもない。
 307 .TP
 308 .B EINVAL
 309 .I flags
 310 が無効である。もしくは、Linux 2.6.26 以前の場合は
 311 .I flags
 312 が 0 以外である。
 313 .TP
 314 .B EMFILE
 315 オープン済みのファイルディスクリプタの数がプロセスあたりの上限に
 316 達していた。
 317 .TP
 318 .B ENFILE
 319 オープン済みのファイル総数がシステム全体の上限に達していた。
 320 .TP
 321 .B ENODEV
 322 (カーネル内の) 無名 inode デバイスをマウントできなかった。
 323 .TP
 324 .B ENOMEM
 325 タイマーを作成するのに十分なカーネルメモリがなかった。
 326 .PP
 327 .BR timerfd_settime ()
 328 と
 329 .BR timerfd_gettime ()
 330 は以下のエラーで失敗する可能性がある。
 331 .TP
 332 .B EBADF
 333 .I fd
 334 が有効なファイルディスクリプタでない。
 335 .TP
 336 .B EFAULT
 337 .IR new_value ,
 338 .IR old_value ,
 339 .I curr_value
 340 が有効なポインタではない。
 341 .TP
 342 .B EINVAL
 343 .I fd
 344 が有効な timerfd ファイルディスクリプタでない。
 345 .PP
 346 .BR timerfd_settime ()
 347 は以下のエラーで失敗することもある。
 348 .TP
 349 .B EINVAL
 350 .I new_value
 351 が適切に初期化されていない
 352 .RI ( tv_nsec
 353 の一つが 0 から 999,999,999 までの範囲に入っていない)。
 354 .TP
 355 .B EINVAL
 356 .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
 357 .\" In older kernel versions, no check was made for invalid flags.
 358 .I flags
 359 が無効である。
 360 .SH バージョン
 361 これらのシステムコールはカーネル 2.6.25 以降の Linux で利用可能である。
 362 ライブラリ側のサポートはバージョン 2.8 以降の glibc で提供されている。
 363 .SH 準拠
 364 これらのシステムコールは Linux 固有である。
 365 .SH 例
 366 以下のプログラムは、タイマーを作成し、その進捗をモニターするものである。
 367 このプログラムは最大で 3 個のコマンドライン引き数を取り、
 368 第一引き数ではタイマーの満了時間の初期値 (秒数単位) を、
 369 第二引き数ではタイマーの間隔 (秒数単位) を、
 370 第三引き数ではタイマーが何回満了したらプログラムが終了するかを指定する。
 371 第二引き数と第三引き数は省略可能である。
 372
 373 以下のシェルのセッションはこのプログラムの使用例を示したものである。
 374 .in +4n
 375 .nf
 376
 377 .RB "$" " a.out 3 1 100"
 378 0.000: timer started
 379 3.000: read: 1; total=1
 380 4.000: read: 1; total=2
 381 .BR "^Z " "                 # type control-Z to suspend the program"
 382 [1]+  Stopped                 ./timerfd3_demo 3 1 100
 383 .RB "$ " "fg" "                # Resume execution after a few seconds"
 384 a.out 3 1 100
 385 9.660: read: 5; total=7
 386 10.000: read: 1; total=8
 387 11.000: read: 1; total=9
 388 .BR "^C " "                 # type control-C to suspend the program"
 389 .fi
 390 .in
 391 .SS プログラムのソース
 392 \&
 393 .nf
 394 .\" The commented out code here is what we currently need until
 395 .\" the required stuff is in glibc
 396 .\"
 397 .\"
 398 .\"/* Link with -lrt */
 399 .\"#define _GNU_SOURCE
 400 .\"#include <sys/syscall.h>
 401 .\"#include <unistd.h>
 402 .\"#include <time.h>
 403 .\"#if defined(__i386__)
 404 .\"#define __NR_timerfd_create 322
 405 .\"#define __NR_timerfd_settime 325
 406 .\"#define __NR_timerfd_gettime 326
 407 .\"#endif
 408 .\"
 409 .\"static int
 410 .\"timerfd_create(int clockid, int flags)
 411 .\"{
 412 .\"    return syscall(__NR_timerfd_create, clockid, flags);
 413 .\"}
 414 .\"
 415 .\"static int
 416 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
 417 .\"        struct itimerspec *curr_value)
 418 .\"{
 419 .\"    return syscall(__NR_timerfd_settime, fd, flags, new_value,
 420 .\"                   curr_value);
 421 .\"}
 422 .\"
 423 .\"static int
 424 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
 425 .\"{
 426 .\"    return syscall(__NR_timerfd_gettime, fd, curr_value);
 427 .\"}
 428 .\"
 429 .\"#define TFD_TIMER_ABSTIME (1 << 0)
 430 .\"
 431 .\"////////////////////////////////////////////////////////////
 432 #include <sys/timerfd.h>
 433 #include <time.h>
 434 #include <unistd.h>
 435 #include <stdlib.h>
 436 #include <stdio.h>
 437 #include <stdint.h>        /* Definition of uint64_t */
 438
 439 #define handle_error(msg) \\
 440         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 441
 442 static void
 443 print_elapsed_time(void)
 444 {
 445     static struct timespec start;
 446     struct timespec curr;
 447     static int first_call = 1;
 448     int secs, nsecs;
 449
 450     if (first_call) {
 451         first_call = 0;
 452         if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
 453             handle_error("clock_gettime");
 454     }
 455
 456     if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
 457         handle_error("clock_gettime");
 458
 459     secs = curr.tv_sec \- start.tv_sec;
 460     nsecs = curr.tv_nsec \- start.tv_nsec;
 461     if (nsecs < 0) {
 462         secs\-\-;
 463         nsecs += 1000000000;
 464     }
 465     printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
 466 }
 467
 468 int
 469 main(int argc, char *argv[])
 470 {
 471     struct itimerspec new_value;
 472     int max_exp, fd;
 473     struct timespec now;
 474     uint64_t exp, tot_exp;
 475     ssize_t s;
 476
 477     if ((argc != 2) && (argc != 4)) {
 478         fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n",
 479                 argv[0]);
 480         exit(EXIT_FAILURE);
 481     }
 482
 483     if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
 484         handle_error("clock_gettime");
 485
 486     /* Create a CLOCK_REALTIME absolute timer with initial
 487        expiration and interval as specified in command line */
 488
 489     new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
 490     new_value.it_value.tv_nsec = now.tv_nsec;
 491     if (argc == 2) {
 492         new_value.it_interval.tv_sec = 0;
 493         max_exp = 1;
 494     } else {
 495         new_value.it_interval.tv_sec = atoi(argv[2]);
 496         max_exp = atoi(argv[3]);
 497     }
 498     new_value.it_interval.tv_nsec = 0;
 499
 500     fd = timerfd_create(CLOCK_REALTIME, 0);
 501     if (fd == \-1)
 502         handle_error("timerfd_create");
 503
 504     if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
 505         handle_error("timerfd_settime");
 506
 507     print_elapsed_time();
 508     printf("timer started\\n");
 509
 510     for (tot_exp = 0; tot_exp < max_exp;) {
 511         s = read(fd, &exp, sizeof(uint64_t));
 512         if (s != sizeof(uint64_t))
 513             handle_error("read");
 514
 515         tot_exp += exp;
 516         print_elapsed_time();
 517         printf("read: %llu; total=%llu\\n",
 518                 (unsigned long long) exp,
 519                 (unsigned long long) tot_exp);
 520     }
 521
 522     exit(EXIT_SUCCESS);
 523 }
 524 .fi
 525 .SH バグ
 526 現在のところ、
 527 .\" 2.6.29
 528 .BR timerfd_create ()
 529 が対応している clockid の種類は
 530 .BR timer_create (2)
 531 よりも少ない。
 532 .SH 関連項目
 533 .BR eventfd (2),
 534 .BR poll (2),
 535 .BR read (2),
 536 .BR select (2),
 537 .BR setitimer (2),
 538 .BR signalfd (2),
 539 .BR timer_create (2),
 540 .BR timer_gettime (2),
 541 .BR timer_settime (2),
 542 .BR epoll (7),
 543 .BR time (7)