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