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