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