draft/man2/poll.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
   4 .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207
  27 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
  28 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
  29 .\"     formatting changes.
  30 .\"
  31 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  32 .\"         all rights reserved.
  33 .\" Translated 1997-12-11, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  34 .\" Updated & Modified 2004-05-22, Yuichi SATO <ysato444@yahoo.co.jp>
  35 .\" Updated & Modified 2005-01-03, Yuichi SATO
  36 .\" Updated & Modified 2005-10-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  37 .\" Updated 2005-12-05, Akihiro MOTOKI, Catch up to LDP man-pages 2.16
  38 .\" Updated 2006-04-16, Akihiro MOTOKI, Catch up to LDP man-pages 2.28
  39 .\" Updated 2006-07-23, Akihiro MOTOKI, Catch up to LDP man-pages 2.36
  40 .\"
  41 .\"WORD:        descriptor              ディスクリプタ
  42 .\"
  43 .TH POLL 2 2010-09-20 "Linux" "Linux Programmer's Manual"
  44 .\"O .SH NAME
  45 .SH 名前
  46 .\"O poll, ppoll \- wait for some event on a file descriptor
  47 poll, ppoll \- ファイルディスクリプタにおけるイベントを待つ
  48 .\"O .SH SYNOPSIS
  49 .SH 書式
  50 .nf
  51 .B #include <poll.h>
  52 .sp
  53 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
  54 .sp
  55 .\"O .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  56 .BR "#define _GNU_SOURCE" "         /* feature_test_macros(7) 参照 */"
  57 .B #include <poll.h>
  58 .sp
  59 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
  60 .BI "        const struct timespec *" timeout_ts ", const sigset_t *" sigmask );
  61 .fi
  62 .\"O .SH DESCRIPTION
  63 .SH 説明
  64 .\"O .BR poll ()
  65 .\"O performs a similar task to
  66 .\"O .BR select (2):
  67 .\"O it waits for one of a set of file descriptors to become ready
  68 .\"O to perform I/O.
  69 .BR poll ()
  70 は
  71 .BR select (2)
  72 と同様の仕事を行う、つまり、ファイルディスクリプタ集合のいずれか一つが
  73 I/O を実行可能な状態になるのを待つ。
  74
  75 .\"O The set of file descriptors to be monitored is specified in the
  76 .\"O .I fds
  77 .\"O argument, which is an array of structures of the following form:
  78 監視するファイルディスクリプタ集合は、
  79 .I fds
  80 引き数で指定する。
  81 .I fds
  82 は、以下の型の構造体の配列である。
  83 .in +4n
  84 .nf
  85
  86 struct pollfd {
  87     int   fd;         /* file descriptor */
  88     short events;     /* requested events */
  89     short revents;    /* returned events */
  90 };
  91 .in
  92 .fi
  93 .PP
  94 .\"O The caller should specify the number of items in the
  95 .\"O .I fds
  96 .\"O array in
  97 .\"O .IR nfds .
  98 .I nfds
  99 には、
 100 .I fds
 101 配列の要素数を指定する。
 102
 103 .\"O The field
 104 .\"O .I fd
 105 .\"O contains a file descriptor for an open file.
 106 構造体の
 107 .I fd
 108 にはオープンしたファイルのファイルディスクリプタを入れる。
 109
 110 .\"O The field
 111 .\"O .I events
 112 .\"O is an input parameter, a bit mask specifying the events the application
 113 .\"O is interested in.
 114 構造体の
 115 .I events
 116 要素は入力パラメータで、アプリケーションが興味を持っているイベントの
 117 ビットマスクを指定する。
 118
 119 .\"O The field
 120 .\"O .I revents
 121 .\"O is an output parameter, filled by the kernel with the events that
 122 .\"O actually occurred.
 123 .\"O The bits returned in
 124 .\"O .I revents
 125 .\"O can include any of those specified in
 126 .\"O .IR events ,
 127 .\"O or one of the values
 128 .\"O .BR POLLERR ,
 129 .\"O .BR POLLHUP ,
 130 .\"O or
 131 .\"O .BR POLLNVAL .
 132 .\"O (These three bits are meaningless in the
 133 .\"O .I events
 134 .\"O field, and will be set in the
 135 .\"O .I revents
 136 .\"O field whenever the corresponding condition is true.)
 137 .I revents
 138 要素は出力パラメータで、実際に起こったイベントがカーネルにより設定される。
 139 .I revents
 140 で返されるビット列には、
 141 .I events
 142 で指定したもののどれか、もしくは
 143 .BR POLLERR ,
 144 .BR POLLHUP ,
 145 .B POLLNVAL
 146 のうちの一つが含まれる
 147 .RB ( POLLERR ,
 148 .BR POLLHUP ,
 149 .B POLLNVAL
 150 の 3つのビットは
 151 .I events
 152 に指定しても意味がなく、対応した状態が真の場合に
 153 .I revents
 154 に設定される)。
 155
 156 .\"O If none of the events requested (and no error) has occurred for any
 157 .\"O of the file descriptors, then
 158 .\"O .BR poll ()
 159 .\"O blocks until one of the events occurs.
 160 どのファイルディスクリプタにも要求したイベントが発生しておらず、
 161 エラーも起こらない場合、
 162 .BR poll ()
 163 はイベントのうちいずれか一つが発生するまで停止 (block) する。
 164
 165 .\"O The
 166 .\"O .I timeout
 167 .\"O argument specifies an upper limit on the time for which
 168 .\"O .BR poll ()
 169 .\"O will block, in milliseconds.
 170 .\"O Specifying a negative value in
 171 .\"O .I timeout
 172 .\"O means an infinite timeout.
 173 .I timeout
 174 引き数は
 175 .BR poll ()
 176 が停止する時間の上限を設定するもので、ミリ秒単位で指定する。
 177 .I timeout
 178 に負の値を指定すると、タイムアウト時間が無限となる。
 179
 180 .\"O The bits that may be set/returned in
 181 .\"O .I events
 182 .\"O and
 183 .\"O .I revents
 184 .\"O are defined in \fI<poll.h>\fP:
 185 .I events
 186 に指定したり、
 187 .I revents
 188 で返されるビットは \fI<poll.h>\fP で定義されている:
 189 .RS
 190 .TP
 191 .B POLLIN
 192 .\"O There is data to read.
 193 読み出し可能なデータがある。
 194 .TP
 195 .B POLLPRI
 196 .\"O There is urgent data to read (e.g., out-of-band data on TCP socket;
 197 .\"O pseudoterminal master in packet mode has seen state change in slave).
 198 読み出し可能な緊急データ (urgent data) がある
 199 (例えば、TCP ソケットの帯域外 (out-of-band data) データを受信した場合や、
 200 パケットモードの擬似端末のマスタがスレーブ側の変化を見つけたとき)。
 201 .TP
 202 .B POLLOUT
 203 .\"O Writing now will not block.
 204 書き込みが停止 (block) しない状態である。
 205 .TP
 206 .\"O .BR POLLRDHUP " (since Linux 2.6.17)"
 207 .BR POLLRDHUP " (Linux 2.6.17 以降)"
 208 .\"O Stream socket peer closed connection,
 209 .\"O or shut down writing half of connection.
 210 .\"O The
 211 .\"O .B _GNU_SOURCE
 212 .\"O feature test macro must be defined
 213 .\"O (before including
 214 .\"O .I any
 215 .\"O header files)
 216 .\"O in order to obtain this definition.
 217 ストリームソケットの他端が、コネクションを close したか、
 218 コネクションの書き込み側を shutdown した。
 219 この定義を有効にするには、
 220 (「どの」ヘッダファイルをインクルードするよりも前に)
 221 .B _GNU_SOURCE
 222 機能検査マクロを定義しなければならない。
 223 .TP
 224 .B POLLERR
 225 .\"O Error condition (output only).
 226 エラー状態 (出力の場合のみ)。
 227 .TP
 228 .B POLLHUP
 229 .\"O Hang up (output only).
 230 ハングアップした (出力の場合のみ)。
 231 .TP
 232 .B POLLNVAL
 233 .\"O Invalid request:
 234 .\"O .I fd
 235 .\"O not open (output only).
 236 不正な要求:
 237 .I fd
 238 がオープンされていない (出力の場合のみ)。
 239 .RE
 240 .PP
 241 .\"O When compiling with
 242 .\"O .B _XOPEN_SOURCE
 243 .\"O defined, one also has the following,
 244 .\"O which convey no further information beyond the bits listed above:
 245 .B _XOPEN_SOURCE
 246 を定義してコンパイルした場合には、以下の定義も行われる。
 247 ただし、上記のリストにあるビット以上の情報が得られる訳ではない。
 248 .RS
 249 .TP
 250 .B POLLRDNORM
 251 .\"O Equivalent to
 252 .\"O .BR POLLIN .
 253 .B POLLIN
 254 と同じ。
 255 .TP
 256 .B POLLRDBAND
 257 .\"O Priority band data can be read (generally unused on Linux).
 258 優先帯域データ (priority band data) が読み出し可能である
 259 (普通は Linux では使用されない)。
 260 .\" POLLRDBAND is used in the DECnet protocol.
 261 .TP
 262 .B POLLWRNORM
 263 .\"O Equivalent to
 264 .\"O .BR POLLOUT .
 265 .B POLLOUT
 266 と同じ。
 267 .TP
 268 .B POLLWRBAND
 269 .\"O Priority data may be written.
 270 優先帯域データ (priority data) が書き込み可能である。
 271 .RE
 272 .PP
 273 .\"O Linux also knows about, but does not use
 274 .\"O .BR POLLMSG .
 275 Linux では
 276 .B POLLMSG
 277 も定義されているが、使用されていない。
 278 .SS ppoll()
 279 .\"O The relationship between
 280 .\"O .BR poll ()
 281 .\"O and
 282 .\"O .BR ppoll ()
 283 .\"O is analogous to the relationship between
 284 .\"O .BR select (2)
 285 .\"O and
 286 .\"O .BR pselect (2):
 287 .\"O like
 288 .\"O .BR pselect (2),
 289 .\"O .BR ppoll ()
 290 .\"O allows an application to safely wait until either a file descriptor
 291 .\"O becomes ready or until a signal is caught.
 292 .BR poll ()
 293 と
 294 .BR ppoll ()
 295 の関係は
 296 .BR select (2)
 297 と
 298 .BR pselect (2)
 299 の関係と同じようなものである:
 300 .BR pselect (2)
 301 と同様に、
 302 .BR ppoll ()
 303 を使うと、アプリケーションはファイルディスクリプタの状態変化
 304 もしくはシグナルの捕捉を安全に待つことができる。
 305 .PP
 306 .\"O Other than the difference in the precision of the
 307 .\"O .I timeout
 308 .\"O argument, the following
 309 .\"O .BR ppoll ()
 310 .\"O call:
 311 .I timeout
 312 引き数の精度の違いを除くと、以下の
 313 .BR ppoll ()
 314 の呼び出しは、
 315 .nf
 316
 317     ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
 318
 319 .fi
 320 .\"O is equivalent to
 321 .\"O .I atomically
 322 .\"O executing the following calls:
 323 次のコールを
 324 .I atomic
 325 に実行するのと等価である。
 326 .nf
 327
 328     sigset_t origmask;
 329     int timeout;
 330
 331     timeout = (timeout_ts == NULL) ? \-1 :
 332               (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
 333     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 334     ready = poll(&fds, nfds, timeout);
 335     sigprocmask(SIG_SETMASK, &origmask, NULL);
 336 .fi
 337 .PP
 338 .\"O See the description of
 339 .\"O .BR pselect (2)
 340 .\"O for an explanation of why
 341 .\"O .BR ppoll ()
 342 .\"O is necessary.
 343 なぜ
 344 .BR ppoll ()
 345 が必要なのかについての説明は
 346 .BR pselect (2)
 347 の説明を参照のこと。
 348
 349 .\"O If the
 350 .\"O .I sigmask
 351 .\"O argument is specified as NULL, then
 352 .\"O no signal mask manipulation is performed
 353 .\"O (and thus
 354 .\"O .BR ppoll ()
 355 .\"O differs from
 356 .\"O .BR poll ()
 357 .\"O only in the precision of the
 358 .\"O .I timeout
 359 .\"O argument).
 360 .I sigmask
 361 引き数に NULL が指定された場合、シグナルマスクの操作は行われない
 362 (したがって、
 363 .BR ppoll ()
 364 の
 365 .BR poll ()
 366 との違いは
 367 .I timeout
 368 引き数の精度だけとなる)。
 369
 370 .\"O The
 371 .\"O .I timeout
 372 .\"O argument specifies an upper limit on the amount of time that
 373 .\"O .BR ppoll ()
 374 .\"O will block.
 375 .\"O This argument is a pointer to a structure of the following form:
 376 .I timeout
 377 引き数は
 378 .BR ppoll ()
 379 が停止する時間の上限を指定するものである。
 380 この引き数には以下の型の構造体へのポインタを指定する。
 381 .in +4n
 382 .nf
 383
 384 struct timespec {
 385     long    tv_sec;         /* seconds */
 386     long    tv_nsec;        /* nanoseconds */
 387 };
 388 .fi
 389 .in
 390
 391 .\"O If
 392 .\"O .I timeout_ts
 393 .\"O is specified as NULL, then
 394 .\"O .BR ppoll ()
 395 .\"O can block indefinitely.
 396 .I timeout_ts
 397 に NULL が指定された場合、
 398 .B ppoll
 399 は無限に停止することがあり得る。
 400 .\"O .SH "RETURN VALUE"
 401 .SH 返り値
 402 .\"O On success, a positive number is returned; this is
 403 .\"O the number of structures which have nonzero
 404 .\"O .I revents
 405 .\"O fields (in other words, those descriptors with events or errors reported).
 406 .\"O A value of 0 indicates that the call timed out and no file
 407 .\"O descriptors were ready.
 408 .\"O On error, \-1 is returned, and
 409 .\"O .I errno
 410 .\"O is set appropriately.
 411 成功した場合は正の数を返す。この数は 0 以外の
 412 .I revents
 413 要素を持つ構造体の数である (別の言い方をすると、これらのディスクリプタ
 414 にはイベントかエラー報告がある)。
 415 値 0 は、タイムアウトとなり、どのファイルディスクリプタでもイベントが
 416 発生しなかったことを示す。エラーの場合は \-1 が返され、
 417 .I errno
 418 が適切に設定される。
 419 .\"O .SH ERRORS
 420 .SH エラー
 421 .TP
 422 .B EFAULT
 423 .\"O The array given as argument was not contained in the calling program's
 424 .\"O address space.
 425 引き数として指定した配列が、呼び出したプロセスのアドレス空間に
 426 含まれていない。
 427 .TP
 428 .B EINTR
 429 .\"O A signal occurred before any requested event; see
 430 .\"O .BR signal (7).
 431 要求されたイベントのどれかが起こる前にシグナルが発生した。
 432 .BR signal (7)
 433 参照。
 434 .TP
 435 .B EINVAL
 436 .\"O The
 437 .\"O .I nfds
 438 .\"O value exceeds the
 439 .\"O .B RLIMIT_NOFILE
 440 .\"O value.
 441 .I nfds
 442 の値が
 443 .B RLIMIT_NOFILE
 444 を超えた。
 445 .TP
 446 .B ENOMEM
 447 .\"O There was no space to allocate file descriptor tables.
 448 ファイルディスクリプタ・テーブルを確保するためのメモリがない。
 449 .\"O .SH VERSIONS
 450 .SH バージョン
 451 .\"O The
 452 .\"O .BR poll ()
 453 .\"O system call was introduced in Linux 2.1.23.
 454 .\"O The
 455 .\"O .BR poll ()
 456 .\"O library call was introduced in libc 5.4.28
 457 .\"O (and provides emulation using
 458 .\"O .BR select (2)
 459 .\"O if your kernel does not
 460 .\"O have a
 461 .\"O .BR poll ()
 462 .\"O system call).
 463 .BR poll ()
 464 システムコールは Linux 2.1.23 で導入された。
 465 .BR poll ()
 466 ライブラリ・コールは libc 5.4.28 から導入された
 467 (これはカーネルが
 468 .BR poll ()
 469 システムコールをサポートしていない場合に
 470 .BR select (2)
 471 を使用してエミュレートを行う)。
 472
 473 .\"O The
 474 .\"O .BR ppoll ()
 475 .\"O system call was added to Linux in kernel 2.6.16.
 476 .\"O The
 477 .\"O .BR ppoll ()
 478 .\"O library call was added in glibc 2.4.
 479 .BR ppoll ()
 480 システムコールは カーネル 2.6.16 で Linux に追加された。
 481 .BR ppoll ()
 482 ライブラリコールは glibc 2.4 に追加された。
 483 .\"O .SH "CONFORMING TO"
 484 .SH 準拠
 485 .\"O .BR poll ()
 486 .\"O conforms to POSIX.1-2001.
 487 .\"O .BR ppoll ()
 488 .\"O is Linux-specific.
 489 .\"O .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
 490 .BR poll ()
 491 は POSIX.1-2001 に準拠している。
 492 .BR ppoll ()
 493 は Linux 固有である。
 494 .\" NetBSD 3.0 には pollts() がある。
 495 .\" pollts() は Linux ppoll () と同じようなものである。
 496 .\"O .SH NOTES
 497 .SH 注意
 498 .\"O Some implementations define the nonstandard constant
 499 .\"O .B INFTIM
 500 .\"O with the value \-1 for use as a
 501 .\"O .IR timeout
 502 .\"O for
 503 .\"O .BR poll ().
 504 .\"O This constant is not provided in glibc.
 505 いくつかの実装では、値 \-1 を持った非標準の定数
 506 .B INFTIM
 507 が定義されており、
 508 .BR poll ()
 509 の
 510 .I timeout
 511 の指定に使用できる。
 512 この定数は glibc では定義されていない。
 513 .\"O .SS "LINUX NOTES"
 514 .SS "Linux での注意"
 515 .\"O The Linux
 516 .\"O .BR ppoll ()
 517 .\"O system call modifies its
 518 .\"O .I timeout_ts
 519 .\"O argument.
 520 .\"O However, the glibc wrapper function hides this behavior
 521 .\"O by using a local variable for the timeout argument that
 522 .\"O is passed to the system call.
 523 .\"O Thus, the glibc
 524 .\"O .BR ppoll ()
 525 .\"O function does not modify its
 526 .\"O .I timeout_ts
 527 .\"O argument.
 528 Linux の
 529 .BR ppoll ()
 530 システムコールは
 531 .I timeout_ts
 532 引き数を変更する。
 533 しかし、glibc のラッパー関数は、システムコールに渡す timeout 引き数
 534 としてローカル変数を使うことでこの動作を隠蔽している。
 535 このため、glibc の
 536 .BR ppoll ()
 537 関数では
 538 .I timeout_ts
 539 引き数は変更されない。
 540 .\"O .SH BUGS
 541 .SH バグ
 542 .\"O See the discussion of spurious readiness notifications under the
 543 .\"O BUGS section of
 544 .\"O .BR select (2).
 545 .BR select (2)
 546 の「バグ」の節に書かれている、誤った準備完了通知 (spurious readiness
 547 notifications) についての議論を参照のこと。
 548 .\"O .SH "SEE ALSO"
 549 .SH 関連項目
 550 .BR select (2),
 551 .BR select_tut (2),
 552 .BR time (7)