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