draft/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 .\"*******************************************************************
  22 .\"
  23 .\" This file was generated with po4a. Translate the source file.
  24 .\"
  25 .\"*******************************************************************
  26 .\"
  27 .\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
  28 .\"         all rights reserved.
  29 .\" Translated 2008-11-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.13
  30 .\" Updated 2009-04-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP 3.20
  31 .\" Updated 2012-05-04, Akihiro MOTOKI <amotoki@gmail.com>
  32 .\"
  33 .TH TIMERFD_CREATE 2 2011\-09\-14 Linux "Linux Programmer's Manual"
  34 .SH 名前
  35 timerfd_create, timerfd_settime, timerfd_gettime \- ファイルディスクリプタ経由で通知するタイマー
  36 .SH 書式
  37 .nf
  38 \fB#include <sys/timerfd.h>\fP
  39 .sp
  40 \fBint timerfd_create(int \fP\fIclockid\fP\fB, int \fP\fIflags\fP\fB);\fP
  41 .sp
  42 \fBint timerfd_settime(int \fP\fIfd\fP\fB, int \fP\fIflags\fP\fB,\fP
  43 \fB                    const struct itimerspec *\fP\fInew_value\fP\fB,\fP
  44 \fB                    struct itimerspec *\fP\fIold_value\fP\fB);\fP
  45 .sp
  46 \fBint timerfd_gettime(int \fP\fIfd\fP\fB, struct itimerspec *\fP\fIcurr_value\fP\fB);\fP
  47 .fi
  48 .SH 説明
  49 これらのシステムコールは、満了通知をファイルディスクリプタ経由で配送する タイマーの生成と操作を行う。 これらは、 \fBsetitimer\fP(2)  や
  50 \fBtimer_create\fP(2)  を用いる方法の代わりとなるものであり、このファイルディスクリプタを \fBselect\fP(2),
  51 \fBpoll\fP(2), \fBepoll\fP(7)  で監視できるという利点がある。
  52
  53 .\"
  54 これらのシステムコールを使うのは、それぞれ \fBtimer_create\fP(2), \fBtimer_settime\fP(2),
  55 \fBtimer_gettime\fP(2)  を使うのと同様である (\fBtimer_getoverrun\fP(2)
  56 に対応するものはなく、以下で説明するように この機能は \fBread\fP(2)  により提供される)。
  57 .SS timerfd_create()
  58 \fBtimerfd_create\fP()  は新規のタイマーオブジェクトを生成し、そのタイマーを参照するファイル ディスクリプタを返す。
  59 \fIclockid\fP 引き数は、タイマーの進捗を管理するためのクロックを指定するもので、 \fBCLOCK_REALTIME\fP か
  60 \fBCLOCK_MONOTONIC\fP のいずれかでなければならない。 \fBCLOCK_REALTIME\fP
  61 はシステム全体で使用されるクロックで、このクロックは変更可能である。 \fBCLOCK_MONOTONIC\fP
  62 は変更されることのないクロックで、(システム時刻の手動での変更などの)  システムクロックの不連続な変化の影響を受けない。 これらのクロックの現在の値は
  63 \fBclock_gettime\fP(2)  を使って取得できる。
  64
  65 Linux 2.6.27 以降では、 以下の値のいくつかをビット単位の論理和 (OR) で指定することで、 \fBtimerfd_create\fP()
  66 の振舞いを変更することができる。
  67 .TP  14
  68 \fBTFD_NONBLOCK\fP
  69 新しく生成されるオープンファイル記述 (open file description) の \fBO_NONBLOCK\fP
  70 ファイルステータスフラグをセットする。 このフラグを使うことで、 \fBO_NONBLOCK\fP をセットするために \fBfcntl\fP(2)
  71 を追加で呼び出す必要がなくなる。
  72 .TP
  73 \fBTFD_CLOEXEC\fP
  74 新しいファイルディスクリプタに対して close\-on\-exec (\fBFD_CLOEXEC\fP)  フラグをセットする。
  75 このフラグが役に立つ理由については、 \fBopen\fP(2)  の \fBO_CLOEXEC\fP フラグの説明を参照のこと。
  76 .PP
  77 バージョン 2.6.26 以前の Linux では、 \fIflags\fP 引き数は未使用であり、0 を指定しなければならない。
  78 .SS timerfd_settime()
  79 \fBtimerfd_settime\fP()  は、ファイルディスクリプタ \fIfd\fP により参照されるタイマーを開始したり停止したりする。
  80
  81 \fInew_value\fP 引き数は、タイマーの満了時間 (expiration) の初期値と間隔 (interval) を
  82 指定する。この引き数で使用されている \fIitimerspec\fP 構造体には 2 つのフィールドがあり、各フィールドは \fItimespec\fP
  83 型の構造体である。
  84 .in +4n
  85 .nf
  86
  87 struct timespec {
  88     time_t tv_sec;                /* Seconds */
  89     long   tv_nsec;               /* Nanoseconds */
  90 };
  91
  92 struct itimerspec {
  93     struct timespec it_interval;  /* Interval for periodic timer */
  94     struct timespec it_value;     /* Initial expiration */
  95 };
  96 .fi
  97 .in
  98 .PP
  99 \fInew_value.it_value\fP はタイマーの満了時間の初期値を、秒とナノ秒で指定する。 \fInew_value.it_value\fP
 100 のフィールドのうち少なくとも一方に 0 以外の値を設定すると、 タイマーが開始される。 両方のフィールドに 0 を設定すると、タイマーが停止する。
 101
 102 \fInew_value.it_interval\fP はタイマーの一回目の満了後に繰り返しタイマーの満了間隔を、秒とナノ秒で指定する。
 103 \fInew_value.it_interval\fP のフィールドのうち少なくとも一方に 0 以外の値を設定すると、 繰り返しタイマーが有効になる。
 104 両方のフィールドに 0 を設定した場合、タイマーは \fInew_value.it_value\fP で指定された時間後に、一回だけ満了して停止する。
 105
 106 \fIflags\fP 引き数には 0 か \fBTFD_TIMER_ABSTIME\fP を指定する。 0 は相対時刻
 107 タイマーを意味し、 \fInew_value.it_value\fP では \fIclockid\fP で指定された
 108 クロックの現在の値からの相対的な時刻を指定する。 \fBTFD_TIMER_ABSTIME\fP
 109 は絶対時刻タイマーを意味し、 \fInew_value.it_interval\fP では \fIclockid\fP
 110 で指定されたクロックの絶対時刻を指定する。
 111 つまり、クロックの値が \fInew_value.it_interval\fP で指定された時刻に
 112 達したら、タイマーが満了する。
 113
 114 .\"
 115 \fIold_value\fP 引き数が NULL でない場合、 \fIold_value\fP 引き数が指す
 116 \fIitimerspec\fP 構造体は、 \fBtimerfd_settime\fP() を呼び出した時点での
 117 タイマーの設定を返すのに使用される。
 118 下記の \fBtimerfd_gettime\fP() の説明を参照。
 119 .SS timerfd_gettime()
 120 \fBtimerfd_gettime\fP()  は、ファイルディスクリプタ \fIfd\fP で参照されるタイマーの現在の設定が入った \fIitimerspec\fP
 121 構造体を、 \fIcurr_value\fP に格納して返す。
 122
 123 \fIit_value\fP フィールドは、タイマーが次に満了するまでの残り時間を返す。 この構造体の両方のフィールドが 0
 124 であれば、タイマーは現在停止している。 タイマー設定時に \fBTFD_TIMER_ABSTIME\fP
 125 フラグが指定されたかに関わらず、このフィールドは常に相対値が格納される。
 126
 127 \fIit_interval\fP フィールドは、タイマーの間隔を返す。 この構造体の両方のフィールドが 0 であれば、タイマーは
 128 \fInew_value.it_value\fP で指定された時間後に一回だけ満了して停止するように設定されている。
 129 .SS タイマー・ファイルディスクリプタに対する操作
 130 \fBtimerfd_create\fP()  が返すファイルディスクリプタは以下の操作をサポートしている。
 131 .TP
 132 \fBread\fP(2)
 133 \fBtimerfd_settime\fP()  を使ってタイマーの設定が最後変更されて以降、または \fBread\fP(2)
 134 の呼び出しに最後に成功して以降に、タイマーの満了が一回以上発生していれば、 \fBread\fP(2)  に渡されたバッファに、タイマー満了回数を示す 8
 135 バイトの unsigned 型の整数 (\fIuint64_t\fP)  が返される (返される値はホストバイトオーダ、つまりそのホストマシンにおける
 136 整数の通常のバイトオーダである)。
 137 .IP
 138 \fBread\fP(2)  を行った時点でタイマーの満了が発生していなければ、 \fBread\fP(2)  は停止 (block)
 139 する、もしくはファイルディスクリプタが 非停止 (nonblocking) に設定されている場合はエラー \fBEAGAIN\fP で失敗する
 140 (非停止モードにするには、 \fBfcntl\fP(2)  の \fBF_SETFL\fP 命令で \fBO_NONBLOCK\fP フラグをセットする)。
 141 .IP
 142 渡されたバッファの大きさが 8 バイト未満の場合、 \fBread\fP(2)  はエラー \fBEINVAL\fP で失敗する。
 143 .TP
 144 \fBpoll\fP(2), \fBselect\fP(2) (と同様の操作)
 145 一つ以上のタイマー満了が発生していれば、 ファイルディスクリプタは読み出し可能となる (\fBselect\fP(2)  の \fIreadfds\fP 引き数や
 146 \fBpoll\fP(2)  の \fBPOLLIN\fP フラグ)。
 147 .IP
 148 このファイルディスクリプタは、他のファイルディスクリプタ多重 API である \fBpselect\fP(2), \fBppoll\fP(2),
 149 \fBepoll\fP(7)  もサポートしている。
 150 .TP
 151 \fBclose\fP(2)
 152 .\"
 153 ファイルディスクリプタがそれ以降は必要なくなった際には、クローズすべきである。 同じ timer
 154 オブジェクトに関連付けられたファイルディスクリプタが全て クローズされると、そのタイマーは解除され、
 155 そのオブジェクト用の資源がカーネルにより解放される。
 156 .SS "fork(2) での扱い"
 157 .\"
 158 \fBfork\fP(2)  が行われると、子プロセスは \fBtimerfd_create\fP()  により生成されたファイルディスクリプタのコピーを
 159 継承する。そのファイルディスクリプタは、親プロセスの対応する ファイルディスクリプタと同じタイマーオブジェクトを参照しており、 子プロセスの
 160 \fBread\fP(2)  でも同じタイマーの満了に関する情報が返される。
 161 .SS "execve(2) での扱い"
 162 \fBexecve\fP(2)  の前後で \fBtimerfd_create\fP()  により生成されたファイルディスクリプタは保持され、
 163 タイマーが開始されていた場合にはタイマーの満了が発生し続ける。
 164 .SH 返り値
 165 成功すると、 \fBtimerfd_create\fP()  は新しいファイルディスクリプタを返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
 166 にエラーを示す値を設定する。
 167
 168 \fBtimerfd_settime\fP()  と \fBtimerfd_gettime\fP()  は成功すると 0 を返す。 エラーの場合、\-1 を返し、
 169 \fIerrno\fP にエラーを示す値を設定する。
 170 .SH エラー
 171 \fBtimerfd_create\fP()  は以下のエラーで失敗する可能性がある。
 172 .TP
 173 \fBEINVAL\fP
 174 \fIclockid\fP 引き数が \fBCLOCK_MONOTONIC\fP でも \fBCLOCK_REALTIME\fP でもない。
 175 .TP
 176 \fBEINVAL\fP
 177 \fIflags\fP が無効である。もしくは、Linux 2.6.26 以前の場合には \fIflags\fP が 0 以外である。
 178 .TP
 179 \fBEMFILE\fP
 180 オープン済みのファイルディスクリプタの数がプロセスあたりの上限に 達していた。
 181 .TP
 182 \fBENFILE\fP
 183 オープン済みのファイル総数がシステム全体の上限に達していた。
 184 .TP
 185 \fBENODEV\fP
 186 (カーネル内の) 無名 inode デバイスをマウントできなかった。
 187 .TP
 188 \fBENOMEM\fP
 189 タイマーを作成するのに十分なカーネルメモリがなかった。
 190 .PP
 191 \fBtimerfd_settime\fP()  と \fBtimerfd_gettime\fP()  は以下のエラーで失敗する可能性がある。
 192 .TP
 193 \fBEBADF\fP
 194 \fIfd\fP が有効なファイルディスクリプタでない。
 195 .TP
 196 \fBEFAULT\fP
 197 \fInew_value\fP, \fIold_value\fP, \fIcurr_value\fP が有効なポインタではない。
 198 .TP
 199 \fBEINVAL\fP
 200 \fIfd\fP が有効な timerfd ファイルディスクリプタでない。
 201 .PP
 202 \fBtimerfd_settime\fP()  は以下のエラーで失敗することもある。
 203 .TP
 204 \fBEINVAL\fP
 205 \fInew_value\fP が適切に初期化されていない (\fItv_nsec\fP の一つが 0 から 999,999,999 までの範囲に入っていない)。
 206 .TP
 207 \fBEINVAL\fP
 208 .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
 209 .\" In older kernel versions, no check was made for invalid flags.
 210 \fIflags\fP が無効である。
 211 .SH バージョン
 212 これらのシステムコールはカーネル 2.6.25 以降の Linux で利用可能である。 ライブラリ側のサポートはバージョン 2.8 以降の glibc
 213 で提供されている。
 214 .SH 準拠
 215 これらのシステムコールは Linux 固有である。
 216 .SH バグ
 217 .\" 2.6.29
 218 現在のところ、 \fBtimerfd_create\fP()  が対応している clockid の種類は \fBtimer_create\fP(2)
 219 よりも少ない。
 220 .SH 例
 221 以下のプログラムは、タイマーを作成し、その進捗をモニターするものである。 このプログラムは最大で 3 個のコマンドライン引き数を取り、
 222 第一引き数ではタイマーの満了時間の初期値 (秒数単位) を、 第二引き数ではタイマーの間隔 (秒数単位) を、
 223 第三引き数ではタイマーが何回満了したらプログラムが終了するかを指定する。 第二引き数と第三引き数は省略可能である。
 224
 225 以下のシェルのセッションはこのプログラムの使用例を示したものである。
 226 .in +4n
 227 .nf
 228
 229 $\fB a.out 3 1 100\fP
 230 0.000: timer started
 231 3.000: read: 1; total=1
 232 4.000: read: 1; total=2
 233 \fB^Z \fP                 # type control\-Z to suspend the program
 234 [1]+  Stopped                 ./timerfd3_demo 3 1 100
 235 $ \fBfg\fP                # Resume execution after a few seconds
 236 a.out 3 1 100
 237 9.660: read: 5; total=7
 238 10.000: read: 1; total=8
 239 11.000: read: 1; total=9
 240 \fB^C \fP                 # type control\-C to suspend the program
 241 .fi
 242 .in
 243 .SS プログラムのソース
 244 \&
 245 .nf
 246 .\" The commented out code here is what we currently need until
 247 .\" the required stuff is in glibc
 248 .\"
 249 .\"
 250 .\"/* Link with -lrt */
 251 .\"#define _GNU_SOURCE
 252 .\"#include <sys/syscall.h>
 253 .\"#include <unistd.h>
 254 .\"#include <time.h>
 255 .\"#if defined(__i386__)
 256 .\"#define __NR_timerfd_create 322
 257 .\"#define __NR_timerfd_settime 325
 258 .\"#define __NR_timerfd_gettime 326
 259 .\"#endif
 260 .\"
 261 .\"static int
 262 .\"timerfd_create(int clockid, int flags)
 263 .\"{
 264 .\"    return syscall(__NR_timerfd_create, clockid, flags);
 265 .\"}
 266 .\"
 267 .\"static int
 268 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
 269 .\"        struct itimerspec *curr_value)
 270 .\"{
 271 .\"    return syscall(__NR_timerfd_settime, fd, flags, new_value,
 272 .\"                   curr_value);
 273 .\"}
 274 .\"
 275 .\"static int
 276 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
 277 .\"{
 278 .\"    return syscall(__NR_timerfd_gettime, fd, curr_value);
 279 .\"}
 280 .\"
 281 .\"#define TFD_TIMER_ABSTIME (1 << 0)
 282 .\"
 283 .\"////////////////////////////////////////////////////////////
 284 #include <sys/timerfd.h>
 285 #include <time.h>
 286 #include <unistd.h>
 287 #include <stdlib.h>
 288 #include <stdio.h>
 289 #include <stdint.h>        /* Definition of uint64_t */
 290
 291 #define handle_error(msg) \e
 292         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 293
 294 static void
 295 print_elapsed_time(void)
 296 {
 297     static struct timespec start;
 298     struct timespec curr;
 299     static int first_call = 1;
 300     int secs, nsecs;
 301
 302     if (first_call) {
 303         first_call = 0;
 304         if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
 305             handle_error("clock_gettime");
 306     }
 307
 308     if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
 309         handle_error("clock_gettime");
 310
 311     secs = curr.tv_sec \- start.tv_sec;
 312     nsecs = curr.tv_nsec \- start.tv_nsec;
 313     if (nsecs < 0) {
 314         secs\-\-;
 315         nsecs += 1000000000;
 316     }
 317     printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
 318 }
 319
 320 int
 321 main(int argc, char *argv[])
 322 {
 323     struct itimerspec new_value;
 324     int max_exp, fd;
 325     struct timespec now;
 326     uint64_t exp, tot_exp;
 327     ssize_t s;
 328
 329     if ((argc != 2) && (argc != 4)) {
 330         fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\en",
 331                 argv[0]);
 332         exit(EXIT_FAILURE);
 333     }
 334
 335     if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
 336         handle_error("clock_gettime");
 337
 338     /* Create a CLOCK_REALTIME absolute timer with initial
 339        expiration and interval as specified in command line */
 340
 341     new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
 342     new_value.it_value.tv_nsec = now.tv_nsec;
 343     if (argc == 2) {
 344         new_value.it_interval.tv_sec = 0;
 345         max_exp = 1;
 346     } else {
 347         new_value.it_interval.tv_sec = atoi(argv[2]);
 348         max_exp = atoi(argv[3]);
 349     }
 350     new_value.it_interval.tv_nsec = 0;
 351
 352     fd = timerfd_create(CLOCK_REALTIME, 0);
 353     if (fd == \-1)
 354         handle_error("timerfd_create");
 355
 356     if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
 357         handle_error("timerfd_settime");
 358
 359     print_elapsed_time();
 360     printf("timer started\en");
 361
 362     for (tot_exp = 0; tot_exp < max_exp;) {
 363         s = read(fd, &exp, sizeof(uint64_t));
 364         if (s != sizeof(uint64_t))
 365             handle_error("read");
 366
 367         tot_exp += exp;
 368         print_elapsed_time();
 369         printf("read: %llu; total=%llu\en",
 370                 (unsigned long long) exp,
 371                 (unsigned long long) tot_exp);
 372     }
 373
 374     exit(EXIT_SUCCESS);
 375 }
 376 .fi
 377 .SH 関連項目
 378 \fBeventfd\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBselect\fP(2), \fBsetitimer\fP(2),
 379 \fBsignalfd\fP(2), \fBtimer_create\fP(2), \fBtimer_gettime\fP(2),
 380 \fBtimer_settime\fP(2), \fBepoll\fP(7), \fBtime\fP(7)
 381 .SH この文書について
 382 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 383 である。プロジェクトの説明とバグ報告に関する情報は
 384 http://www.kernel.org/doc/man\-pages/ に書かれている。