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 .\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
  19 .\"         all rights reserved.
  20 .\" Translated 2008-11-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.13
  21 .\" Updated 2009-04-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP 3.20
  22 .\"
  23 .TH TIMERFD_CREATE 2 2009-03-10 Linux "Linux Programmer's Manual"
  24 .\"O .SH NAME
  25 .SH 名前
  26 .\"O timerfd_create, timerfd_settime, timerfd_gettime \-
  27 .\"O timers that notify via file descriptors
  28 timerfd_create, timerfd_settime, timerfd_gettime \-
  29 ファイルディスクリプタ経由で通知するタイマー
  30 .\"O .SH SYNOPSIS
  31 .SH 書式
  32 .nf
  33 .B #include <sys/timerfd.h>
  34 .sp
  35 .BI "int timerfd_create(int " clockid ", int " flags );
  36 .sp
  37 .BI "int timerfd_settime(int " fd ", int " flags ,
  38 .BI "                    const struct itimerspec *" new_value ,
  39 .BI "                    struct itimerspec *" old_value );
  40 .sp
  41 .BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value );
  42 .fi
  43 .\"O .SH DESCRIPTION
  44 .SH 説明
  45 .\"O These system calls create and operate on a timer
  46 .\"O that delivers timer expiration notifications via a file descriptor.
  47 .\"O They provide an alternative to the use of
  48 .\"O .BR setitimer (2)
  49 .\"O or
  50 .\"O .BR timer_create (2),
  51 .\"O with the advantage that the file descriptor may be monitored by
  52 .\"O .BR select (2),
  53 .\"O .BR poll (2),
  54 .\"O and
  55 .\"O .BR epoll (7).
  56 これらのシステムコールは、満了通知をファイルディスクリプタ経由で配送する
  57 タイマーの生成と操作を行う。
  58 これらは、
  59 .BR setitimer (2)
  60 や
  61 .BR timer_create (2)
  62 を用いる方法の代わりとなるものであり、このファイルディスクリプタを
  63 .BR select (2),
  64 .BR poll (2),
  65 .BR epoll (7)
  66 で監視できるという利点がある。
  67
  68 .\"O The use of these three system calls is analogous to the use of
  69 .\"O .BR timer_create (2),
  70 .\"O .BR timer_settime (2),
  71 .\"O and
  72 .\"O .BR timer_gettime (2).
  73 .\"O (There is no analog of
  74 .\"O .BR timer_getoverrun (2),
  75 .\"O since that functionality is provided by
  76 .\"O .BR read (2),
  77 .\"O as described below.)
  78 これらのシステムコールを使うのは、それぞれ
  79 .BR timer_create (2),
  80 .BR timer_settime (2),
  81 .BR timer_gettime (2)
  82 を使うのと同様である
  83 .RB ( timer_getoverrun (2)
  84 に対応するものはなく、以下で説明するように
  85 この機能は
  86 .BR read (2)
  87 により提供される)。
  88 .\"
  89 .SS timerfd_create()
  90 .\"O .BR timerfd_create ()
  91 .\"O creates a new timer object,
  92 .\"O and returns a file descriptor that refers to that timer.
  93 .BR timerfd_create ()
  94 は新規のタイマーオブジェクトを生成し、そのタイマーを参照するファイル
  95 ディスクリプタを返す。
  96 .\"O The
  97 .\"O .I clockid
  98 .\"O argument specifies the clock that is used to mark the progress
  99 .\"O of the timer, and must be either
 100 .\"O .B CLOCK_REALTIME
 101 .\"O or
 102 .\"O .BR CLOCK_MONOTONIC .
 103 .\"O .B CLOCK_REALTIME
 104 .\"O is a settable system-wide clock.
 105 .\"O .B CLOCK_MONOTONIC
 106 .\"O is a nonsettable clock that is not affected
 107 .\"O by discontinuous changes in the system clock
 108 .\"O (e.g., manual changes to system time).
 109 .\"O The current value of each of these clocks can be retrieved using
 110 .\"O .BR clock_gettime (2).
 111 .I clockid
 112 引き数は、タイマーの進捗を管理するためのクロックを指定するもので、
 113 .B CLOCK_REALTIME
 114 か
 115 .B CLOCK_MONOTONIC
 116 のいずれかでなければならない。
 117 .B CLOCK_REALTIME
 118 はシステム全体で使用されるクロックで、このクロックは変更可能である。
 119 .B CLOCK_MONOTONIC
 120 は変更されることのないクロックで、(システム時刻の手動での変更などの)
 121 システムクロックの不連続な変化の影響を受けない。
 122 これらのクロックの現在の値は
 123 .BR clock_gettime (2)
 124 を使って取得できる。
 125
 126 .\"O Starting with Linux 2.6.27, the following values may be bitwise ORed in
 127 .\"O .IR flags
 128 .\"O to change the behavior of
 129 .\"O .BR timerfd_create ():
 130 Linux 2.6.27 以降では、
 131 以下の値のいくつかをビット単位の論理和 (OR) で指定することで、
 132 .BR timerfd_create ()
 133 の振舞いを変更することができる。
 134 .TP 14
 135 .B TFD_NONBLOCK
 136 .\"O Set the
 137 .\"O .BR O_NONBLOCK
 138 .\"O file status flag on the new open file description.
 139 .\"O Using this flag saves extra calls to
 140 .\"O .BR fcntl (2)
 141 .\"O to achieve the same result.
 142 新しく生成されるオープンファイル記述 (open file description) の
 143 .B O_NONBLOCK
 144 ファイルステータスフラグをセットする。
 145 このフラグを使うことで、
 146 .B O_NONBLOCK
 147 をセットするために
 148 .BR fcntl (2)
 149 を追加で呼び出す必要がなくなる。
 150 .TP
 151 .B TFD_CLOEXEC
 152 .\"O Set the close-on-exec
 153 .\"O .RB ( FD_CLOEXEC )
 154 .\"O flag on the new file descriptor.
 155 .\"O See the description of the
 156 .\"O .B O_CLOEXEC
 157 .\"O flag in
 158 .\"O .BR open (2)
 159 .\"O for reasons why this may be useful.
 160 新しいファイルディスクリプタに対して
 161 close-on-exec
 162 .RB ( FD_CLOEXEC )
 163 フラグをセットする。
 164 このフラグが役に立つ理由については、
 165 .BR open (2)
 166 の
 167 .B O_CLOEXEC
 168 フラグの説明を参照のこと。
 169 .PP
 170 .\"O In Linux versions up to and including 2.6.26,
 171 .\"O .I flags
 172 .\"O must be specified as zero.
 173 バージョン 2.6.26 以前の Linux では、
 174 .I flags
 175 引き数は未使用であり、0 を指定しなければならない。
 176 .SS timerfd_settime()
 177 .\"O .BR timerfd_settime ()
 178 .\"O arms (starts) or disarms (stops)
 179 .\"O the timer referred to by the file descriptor
 180 .\"O .IR fd .
 181 .BR timerfd_settime ()
 182 は、ファイルディスクリプタ
 183 .I fd
 184 により参照されるタイマーを開始したり停止したりする。
 185
 186 .\"O The
 187 .\"O .I new_value
 188 .\"O argument specifies the initial expiration and interval for the timer.
 189 .\"O The
 190 .\"O .I itimer
 191 .\"O structure used for this argument contains two fields,
 192 .\"O each of which is in turn a structure of type
 193 .\"O .IR timespec :
 194 .I new_value
 195 引き数は、タイマーの満了時間 (expiration) の初期値と間隔 (interval) を
 196 指定する。この引き数で使用されている
 197 .\"Omotoki: itimer structure は itimerspec structure の間違いだろう。
 198 .I itimerspec
 199 構造体には 2 つのフィールドがあり、各フィールドは
 200 .I timespec
 201 型の構造体である。
 202 .in +4n
 203 .nf
 204
 205 struct timespec {
 206     time_t tv_sec;                /* Seconds */
 207     long   tv_nsec;               /* Nanoseconds */
 208 };
 209
 210 struct itimerspec {
 211     struct timespec it_interval;  /* Interval for periodic timer */
 212     struct timespec it_value;     /* Initial expiration */
 213 };
 214 .fi
 215 .in
 216 .PP
 217 .\"O .I new_value.it_value
 218 .\"O specifies the initial expiration of the timer,
 219 .\"O in seconds and nanoseconds.
 220 .\"O Setting either field of
 221 .\"O .I new_value.it_value
 222 .\"O to a nonzero value arms the timer.
 223 .\"O Setting both fields of
 224 .\"O .I new_value.it_value
 225 .\"O to zero disarms the timer.
 226 .I new_value.it_value
 227 はタイマーの満了時間の初期値を、秒とナノ秒で指定する。
 228 .I new_value.it_value
 229 のフィールドのうち少なくとも一方に 0 以外の値を設定すると、
 230 タイマーが開始される。
 231 両方のフィールドに 0 を設定すると、タイマーが停止する。
 232
 233 .\"O Setting one or both fields of
 234 .\"O .I new_value.it_interval
 235 .\"O to nonzero values specifies the period, in seconds and nanoseconds,
 236 .\"O for repeated timer expirations after the initial expiration.
 237 .\"O If both fields of
 238 .\"O .I new_value.it_interval
 239 .\"O are zero, the timer expires just once, at the time specified by
 240 .\"O .IR new_value.it_value .
 241 .I new_value.it_interval
 242 はタイマーの一回目の満了後に繰り返しタイマーの満了間隔を、秒とナノ秒で指定する。
 243 .I new_value.it_interval
 244 のフィールドのうち少なくとも一方に 0 以外の値を設定すると、
 245 繰り返しタイマーが有効になる。
 246 両方のフィールドに 0 を設定した場合、タイマーは
 247 .I new_value.it_value
 248 で指定された時間後に、一回だけ満了して停止する。
 249
 250 .\"O The
 251 .\"O .I flags
 252 .\"O argument is either 0, to start a relative timer
 253 .\"O .RI ( new_value.it_interval
 254 .\"O specifies a time relative to the current value of the clock specified by
 255 .\"O .IR clockid ),
 256 .\"O or
 257 .\"O .BR TFD_TIMER_ABSTIME ,
 258 .\"O to start an absolute timer
 259 .\"O .RI ( new_value.it_value
 260 .\"O specifies an absolute time for the clock specified by
 261 .\"O .IR clockid ;
 262 .\"O that is, the timer will expire when the value of that
 263 .\"O clock reaches the value specified in
 264 .\"O .IR new_value.it_value ).
 265 .I flags
 266 引き数には 0 か
 267 .B TFD_TIMER_ABSTIME
 268 を指定する。
 269 0 は相対時刻タイマーを意味し、
 270 .I new_value.it_interval
 271 では
 272 .I clockid
 273 で指定されたクロックの現在の値からの相対的な時刻を指定する。
 274 .B TFD_TIMER_ABSTIME
 275 は絶対時刻タイマーを意味し、
 276 .I new_value.it_interval
 277 では
 278 .I clockid
 279 で指定されたクロックの絶対時刻を指定する。つまり、
 280 クロックの値が
 281 .I new_value.it_interval
 282 で指定された時刻に達したら、タイマーが満了する。
 283
 284 .\"O The
 285 .\"O .I old_value
 286 .\"O argument returns a structure containing the setting of the timer that
 287 .\"O was current at the time of the call; see the description of
 288 .\"O .BR timerfd_gettime ()
 289 .\"O following.
 290 .I old_value
 291 引き数を通じて、
 292 .BR timerfd_settime ()
 293 を呼び出した時点でのタイマーの設定を保持した構造体が返される。
 294 下記の
 295 .BR timerfd_gettime ()
 296 の説明を参照。
 297 .\"
 298 .SS timerfd_gettime()
 299 .\"O .BR timerfd_gettime ()
 300 .\"O returns, in
 301 .\"O .IR curr_value ,
 302 .\"O an
 303 .\"O .IR itimerspec
 304 .\"O structure that contains the current setting of the timer
 305 .\"O referred to by the file descriptor
 306 .\"O .IR fd .
 307 .BR timerfd_gettime ()
 308 は、ファイルディスクリプタ
 309 .I fd
 310 で参照されるタイマーの現在の設定が入った
 311 .I itimerspec
 312 構造体を、
 313 .I curr_value
 314 に格納して返す。
 315
 316 .\"O The
 317 .\"O .I it_value
 318 .\"O field returns the amount of time
 319 .\"O until the timer will next expire.
 320 .\"O If both fields of this structure are zero,
 321 .\"O then the timer is currently disarmed.
 322 .\"O This field always contains a relative value, regardless of whether the
 323 .\"O .BR TFD_TIMER_ABSTIME
 324 .\"O flag was specified when setting the timer.
 325 .I it_value
 326 フィールドは、タイマーが次に満了するまでの残り時間を返す。
 327 この構造体の両方のフィールドが 0 であれば、タイマーは現在停止している。
 328 タイマー設定時に
 329 .B TFD_TIMER_ABSTIME
 330 フラグが指定されたかに関わらず、このフィールドは常に相対値が格納される。
 331
 332 .\"O The
 333 .\"O .I it_interval
 334 .\"O field returns the interval of the timer.
 335 .\"O If both fields of this structure are zero,
 336 .\"O then the timer is set to expire just once, at the time specified by
 337 .\"O .IR curr_value.it_value .
 338 .I it_interval
 339 フィールドは、タイマーの間隔を返す。
 340 この構造体の両方のフィールドが 0 であれば、タイマーは
 341 .I new_value.it_value
 342 で指定された時間後に一回だけ満了して停止するように設定されている。
 343 .\"O .SS Operating on a timer file descriptor
 344 .SS タイマー・ファイルディスクリプタに対する操作
 345 .\"O The file descriptor returned by
 346 .\"O .BR timerfd_create ()
 347 .\"O supports the following operations:
 348 .BR timerfd_create ()
 349 が返すファイルディスクリプタは以下の操作をサポートしている。
 350 .TP
 351 .BR read (2)
 352 .\"O If the timer has already expired one or more times since
 353 .\"O its settings were last modified using
 354 .\"O .BR timerfd_settime (),
 355 .\"O or since the last successful
 356 .\"O .BR read (2),
 357 .\"O then the buffer given to
 358 .\"O .BR read (2)
 359 .\"O returns an unsigned 8-byte integer
 360 .\"O .RI ( uint64_t )
 361 .\"O containing the number of expirations that have occurred.
 362 .\"O (The returned value is in host byte order,
 363 .\"O i.e., the native byte order for integers on the host machine.)
 364 .BR timerfd_settime ()
 365 を使ってタイマーの設定が最後変更されて以降、または
 366 .BR read (2)
 367 の呼び出しに最後に成功して以降に、タイマーの満了が一回以上発生していれば、
 368 .BR read (2)
 369 に渡されたバッファに、タイマー満了回数を示す 8 バイトの unsigned 型の整数
 370 .RI ( uint64_t )
 371 が返される
 372 (返される値はホストバイトオーダ、つまりそのホストマシンにおける
 373 整数の通常のバイトオーダである)。
 374 .IP
 375 .\"O If no timer expirations have occurred at the time of the
 376 .\"O .BR read (2),
 377 .\"O then the call either blocks until the next timer expiration,
 378 .\"O or fails with the error
 379 .\"O .B EAGAIN
 380 .\"O if the file descriptor has been made nonblocking
 381 .\"O (via the use of the
 382 .\"O .BR fcntl (2)
 383 .\"O .B F_SETFL
 384 .\"O operation to set the
 385 .\"O .B O_NONBLOCK
 386 .\"O flag).
 387 .BR read (2)
 388 を行った時点でタイマーの満了が発生していなければ、
 389 .BR read (2)
 390 は停止 (block) する、もしくはファイルディスクリプタが
 391 非停止 (nonblocking) に設定されている場合はエラー
 392 .B EAGAIN
 393 で失敗する (非停止モードにするには、
 394 .BR fcntl (2)
 395 の
 396 .B F_SETFL
 397 命令で
 398 .B O_NONBLOCK
 399 フラグをセットする)。
 400 .IP
 401 .\"O A
 402 .\"O .BR read (2)
 403 .\"O will fail with the error
 404 .\"O .B EINVAL
 405 .\"O if the size of the supplied buffer is less than 8 bytes.
 406 渡されたバッファのサイズが 8 バイト未満の場合、
 407 .BR read (2)
 408 はエラー
 409 .B EINVAL
 410 で失敗する。
 411 .TP
 412 .\"O .BR poll "(2), " select "(2) (and similar)"
 413 .BR poll "(2), " select "(2) (と同様の操作)"
 414 .\"O The file descriptor is readable
 415 .\"O (the
 416 .\"O .BR select (2)
 417 .\"O .I readfds
 418 .\"O argument; the
 419 .\"O .BR poll (2)
 420 .\"O .B POLLIN
 421 .\"O flag)
 422 .\"O if one or more timer expirations have occurred.
 423 一つ以上のタイマー満了が発生していれば、
 424 ファイルディスクリプタは読み出し可能となる
 425 .RB ( select (2)
 426 の
 427 .I readfds
 428 引き数や
 429 .BR poll (2)
 430 の
 431 .B POLLIN
 432 フラグ)。
 433 .IP
 434 .\"O The file descriptor also supports the other file-descriptor
 435 .\"O multiplexing APIs:
 436 .\"O .BR pselect (2),
 437 .\"O .BR ppoll (2),
 438 .\"O and
 439 .\"O .BR epoll (7).
 440 このファイルディスクリプタは、他のファイルディスクリプタ多重 API である
 441 .BR pselect (2),
 442 .BR ppoll (2),
 443 .BR epoll (7)
 444 もサポートしている。
 445 .TP
 446 .BR close (2)
 447 .\"O When the file descriptor is no longer required it should be closed.
 448 .\"O When all file descriptors associated with the same timer object
 449 .\"O have been closed,
 450 .\"O the timer is disarmed and its resources are freed by the kernel.
 451 ファイルディスクリプタがそれ以降は必要なくなった際には、クローズすべきである。
 452 同じ timer オブジェクトに関連付けられたファイルディスクリプタが全て
 453 クローズされると、そのタイマーは解除され、
 454 そのオブジェクト用の資源がカーネルにより解放される。
 455 .\"
 456 .\"O .SS fork(2) semantics
 457 .SS fork(2) での扱い
 458 .\"O After a
 459 .\"O .BR fork (2),
 460 .\"O the child inherits a copy of the file descriptor created by
 461 .\"O .BR timerfd_create ().
 462 .\"O The file descriptor refers to the same underlying
 463 .\"O timer object as the corresponding file descriptor in the parent,
 464 .\"O and
 465 .\"O .BR read (2)s
 466 .\"O in the child will return information about
 467 .\"O expirations of the timer.
 468 .BR fork (2)
 469 が行われると、子プロセスは
 470 .BR timerfd_create ()
 471 により生成されたファイルディスクリプタのコピーを
 472 継承する。そのファイルディスクリプタは、親プロセスの対応する
 473 ファイルディスクリプタと同じタイマーオブジェクトを参照しており、
 474 子プロセスの
 475 .BR read (2)
 476 でも同じタイマーの満了に関する情報が返される。
 477 .\"
 478 .\"O .SS execve(2) semantics
 479 .SS execve(2) での扱い
 480 .\"O A file descriptor created by
 481 .\"O .BR timerfd_create ()
 482 .\"O is preserved across
 483 .\"O .BR execve (2),
 484 .\"O and continues to generate timer expirations if the timer was armed.
 485 .BR execve (2)
 486 の前後で
 487 .BR timerfd_create ()
 488 により生成されたファイルディスクリプタは保持され、
 489 タイマーが開始されていた場合にはタイマーの満了が発生し続ける。
 490 .\"O .SH "RETURN VALUE"
 491 .SH 返り値
 492 .\"O On success,
 493 .\"O .BR timerfd_create ()
 494 .\"O returns a new file descriptor.
 495 .\"O On error, \-1 is returned and
 496 .\"O .I errno
 497 .\"O is set to indicate the error.
 498 成功すると、
 499 .BR timerfd_create ()
 500 は新しいファイルディスクリプタを返す。
 501 エラーの場合、\-1 を返し、
 502 .I errno
 503 にエラーを示す値を設定する。
 504
 505 .\"O .BR timerfd_settime ()
 506 .\"O and
 507 .\"O .BR timerfd_gettime ()
 508 .\"O return 0 on success;
 509 .\"O on error they return \-1, and set
 510 .\"O .I errno
 511 .\"O to indicate the error.
 512 .BR timerfd_settime ()
 513 と
 514 .BR timerfd_gettime ()
 515 は成功すると 0 を返す。
 516 エラーの場合、\-1 を返し、
 517 .I errno
 518 にエラーを示す値を設定する。
 519 .\"O .SH ERRORS
 520 .SH エラー
 521 .\"O .BR timerfd_create ()
 522 .\"O can fail with the following errors:
 523 .BR timerfd_create ()
 524 は以下のエラーで失敗する可能性がある。
 525 .TP
 526 .B EINVAL
 527 .\"O The
 528 .\"O .I clockid
 529 .\"O argument is neither
 530 .\"O .B CLOCK_MONOTONIC
 531 .\"O nor
 532 .\"O .BR CLOCK_REALTIME ;
 533 .I clockid
 534 引き数が
 535 .B CLOCK_MONOTONIC
 536 でも
 537 .B CLOCK_REALTIME
 538 でもない。
 539 .TP
 540 .B EINVAL
 541 .\"O .I flags
 542 .\"O is invalid;
 543 .\"O or, in Linux 2.6.26 or earlier,
 544 .\"O .I flags
 545 .\"O is nonzero.
 546 .I flags
 547 が無効である。もしくは、Linux 2.6.26 以前の場合は
 548 .I flags
 549 が 0 以外である。
 550 .TP
 551 .B EMFILE
 552 .\"O The per-process limit of open file descriptors has been reached.
 553 オープン済みのファイルディスクリプタの数がプロセスあたりの上限に
 554 達していた。
 555 .TP
 556 .B ENFILE
 557 .\"O The system-wide limit on the total number of open files has been
 558 .\"O reached.
 559 オープン済みのファイル総数がシステム全体の上限に達していた。
 560 .TP
 561 .B ENODEV
 562 .\"O Could not mount (internal) anonymous inode device.
 563 (カーネル内の) 無名 inode デバイスをマウントできなかった。
 564 .TP
 565 .B ENOMEM
 566 .\"O There was insufficient kernel memory to create the timer.
 567 タイマーを作成するのに十分なカーネルメモリがなかった。
 568 .PP
 569 .\"O .BR timerfd_settime ()
 570 .\"O and
 571 .\"O .BR timerfd_gettime ()
 572 .\"O can fail with the following errors:
 573 .BR timerfd_settime ()
 574 と
 575 .BR timerfd_gettime ()
 576 は以下のエラーで失敗する可能性がある。
 577 .TP
 578 .B EBADF
 579 .\"O .I fd
 580 .\"O is not a valid file descriptor.
 581 .I fd
 582 が有効なファイルディスクリプタでない。
 583 .TP
 584 .B EFAULT
 585 .\"O .IR new_value ,
 586 .\"O .IR old_value ,
 587 .\"O or
 588 .\"O .I curr_value
 589 .\"O is not valid a pointer.
 590 .IR new_value ,
 591 .IR old_value ,
 592 .I curr_value
 593 が有効なポインタではない。
 594 .TP
 595 .B EINVAL
 596 .\"O .I fd
 597 .\"O is not a valid timerfd file descriptor.
 598 .I fd
 599 が有効な timerfd ファイルディスクリプタでない。
 600 .PP
 601 .\"O .BR timerfd_settime ()
 602 .\"O can also fail with the following errors:
 603 .BR timerfd_settime ()
 604 は以下のエラーで失敗することもある。
 605 .TP
 606 .B EINVAL
 607 .\"O .I new_value
 608 .\"O is not properly initialized (one of the
 609 .\"O .I tv_nsec
 610 .\"O falls outside the range zero to 999,999,999).
 611 .I new_value
 612 が適切に初期化されていない
 613 .RI ( tv_nsec
 614 の一つが 0 から 999,999,999 までの範囲に入っていない)。
 615 .TP
 616 .B EINVAL
 617 .\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version.
 618 .\" In older kernel versions, no check was made for invalid flags.
 619 .\"O .I flags
 620 .\"O is invalid.
 621 .I flags
 622 が無効である。
 623 .\"O .SH VERSIONS
 624 .SH バージョン
 625 .\"O These system calls are available on Linux since kernel 2.6.25.
 626 .\"O Library support is provided by glibc since version 2.8.
 627 これらのシステムコールはカーネル 2.6.25 以降の Linux で利用可能である。
 628 ライブラリ側のサポートはバージョン 2.8 以降の glibc で提供されている。
 629 .\"O .SH CONFORMING TO
 630 .SH 準拠
 631 .\"O These system calls are Linux-specific.
 632 これらのシステムコールは Linux 固有である。
 633 .\"O .SH EXAMPLE
 634 .SH 例
 635 .\"O The following program creates a timer and then monitors its progress.
 636 .\"O The program accepts up to three command-line arguments.
 637 .\"O The first argument specifies the number of seconds for
 638 .\"O the initial expiration of the timer.
 639 .\"O The second argument specifies the interval for the timer, in seconds.
 640 .\"O The third argument specifies the number of times the program should
 641 .\"O allow the timer to expire before terminating.
 642 .\"O The second and third command-line arguments are optional.
 643 以下のプログラムは、タイマーを作成し、その進捗をモニターするものである。
 644 このプログラムは最大で 3 個のコマンドライン引き数を取り、
 645 第一引き数ではタイマーの満了時間の初期値 (秒数単位) を、
 646 第二引き数ではタイマーの間隔 (秒数単位) を、
 647 第三引き数ではタイマーが何回満了したらプログラムが終了するかを指定する。
 648 第二引き数と第三引き数は省略可能である。
 649
 650 .\"O The following shell session demonstrates the use of the program:
 651 以下のシェルのセッションはこのプログラムの使用例を示したものである。
 652 .in +4n
 653 .nf
 654
 655 .RB "$" " a.out 3 1 100"
 656 0.000: timer started
 657 3.000: read: 1; total=1
 658 4.000: read: 1; total=2
 659 .BR "^Z " "                 # type control-Z to suspend the program"
 660 [1]+  Stopped                 ./timerfd3_demo 3 1 100
 661 .RB "$ " "fg" "                # Resume execution after a few seconds"
 662 a.out 3 1 100
 663 9.660: read: 5; total=7
 664 10.000: read: 1; total=8
 665 11.000: read: 1; total=9
 666 .BR "^C " "                 # type control-C to suspend the program"
 667 .fi
 668 .in
 669 .\"O .SS Program source
 670 .SS プログラムのソース
 671 \&
 672 .nf
 673 .\" The commented out code here is what we currently need until
 674 .\" the required stuff is in glibc
 675 .\"
 676 .\"
 677 .\"/* Link with -lrt */
 678 .\"#define _GNU_SOURCE
 679 .\"#include <sys/syscall.h>
 680 .\"#include <unistd.h>
 681 .\"#include <time.h>
 682 .\"#if defined(__i386__)
 683 .\"#define __NR_timerfd_create 322
 684 .\"#define __NR_timerfd_settime 325
 685 .\"#define __NR_timerfd_gettime 326
 686 .\"#endif
 687 .\"
 688 .\"static int
 689 .\"timerfd_create(int clockid, int flags)
 690 .\"{
 691 .\"    return syscall(__NR_timerfd_create, clockid, flags);
 692 .\"}
 693 .\"
 694 .\"static int
 695 .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value,
 696 .\"        struct itimerspec *curr_value)
 697 .\"{
 698 .\"    return syscall(__NR_timerfd_settime, fd, flags, new_value,
 699 .\"                   curr_value);
 700 .\"}
 701 .\"
 702 .\"static int
 703 .\"timerfd_gettime(int fd, struct itimerspec *curr_value)
 704 .\"{
 705 .\"    return syscall(__NR_timerfd_gettime, fd, curr_value);
 706 .\"}
 707 .\"
 708 .\"#define TFD_TIMER_ABSTIME (1 << 0)
 709 .\"
 710 .\"////////////////////////////////////////////////////////////
 711 #include <sys/timerfd.h>
 712 #include <time.h>
 713 #include <unistd.h>
 714 #include <stdlib.h>
 715 #include <stdio.h>
 716 #include <stdint.h>        /* Definition of uint64_t */
 717
 718 #define handle_error(msg) \\
 719         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 720
 721 static void
 722 print_elapsed_time(void)
 723 {
 724     static struct timespec start;
 725     struct timespec curr;
 726     static int first_call = 1;
 727     int secs, nsecs;
 728
 729     if (first_call) {
 730         first_call = 0;
 731         if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1)
 732             handle_error("clock_gettime");
 733     }
 734
 735     if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1)
 736         handle_error("clock_gettime");
 737
 738     secs = curr.tv_sec \- start.tv_sec;
 739     nsecs = curr.tv_nsec \- start.tv_nsec;
 740     if (nsecs < 0) {
 741         secs\-\-;
 742         nsecs += 1000000000;
 743     }
 744     printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
 745 }
 746
 747 int
 748 main(int argc, char *argv[])
 749 {
 750     struct itimerspec new_value;
 751     int max_exp, fd;
 752     struct timespec now;
 753     uint64_t exp, tot_exp;
 754     ssize_t s;
 755
 756     if ((argc != 2) && (argc != 4)) {
 757         fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n",
 758                 argv[0]);
 759         exit(EXIT_FAILURE);
 760     }
 761
 762     if (clock_gettime(CLOCK_REALTIME, &now) == \-1)
 763         handle_error("clock_gettime");
 764
 765     /* Create a CLOCK_REALTIME absolute timer with initial
 766        expiration and interval as specified in command line */
 767
 768     new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);
 769     new_value.it_value.tv_nsec = now.tv_nsec;
 770     if (argc == 2) {
 771         new_value.it_interval.tv_sec = 0;
 772         max_exp = 1;
 773     } else {
 774         new_value.it_interval.tv_sec = atoi(argv[2]);
 775         max_exp = atoi(argv[3]);
 776     }
 777     new_value.it_interval.tv_nsec = 0;
 778
 779     fd = timerfd_create(CLOCK_REALTIME, 0);
 780     if (fd == \-1)
 781         handle_error("timerfd_create");
 782
 783     if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1)
 784         handle_error("timerfd_settime");
 785
 786     print_elapsed_time();
 787     printf("timer started\\n");
 788
 789     for (tot_exp = 0; tot_exp < max_exp;) {
 790         s = read(fd, &exp, sizeof(uint64_t));
 791         if (s != sizeof(uint64_t))
 792             handle_error("read");
 793
 794         tot_exp += exp;
 795         print_elapsed_time();
 796         printf("read: %llu; total=%llu\\n",
 797                 (unsigned long long) exp,
 798                 (unsigned long long) tot_exp);
 799     }
 800
 801     exit(EXIT_SUCCESS);
 802 }
 803 .fi
 804 .\"O .SH BUGS
 805 .SH バグ
 806 .\"O Currently,
 807 .\"O .\" 2.6.29
 808 .\"O .BR timerfd_create ()
 809 .\"O supports fewer types of clock IDs than
 810 .\"O .BR timer_create (2).
 811 現在のところ、
 812 .\" 2.6.29
 813 .BR timerfd_create ()
 814 が対応している clockid の種類は
 815 .BR timer_create (2)
 816 よりも少ない。
 817 .\"O .SH "SEE ALSO"
 818 .SH 関連項目
 819 .BR eventfd (2),
 820 .BR poll (2),
 821 .BR read (2),
 822 .BR select (2),
 823 .BR setitimer (2),
 824 .BR signalfd (2),
 825 .BR timer_create (2),
 826 .BR timer_gettime (2),
 827 .BR timer_settime (2),
 828 .BR epoll (7),
 829 .BR time (7)