release/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 .SH 名前
  45 poll, ppoll \- ファイルディスクリプタにおけるイベントを待つ
  46 .SH 書式
  47 .nf
  48 .B #include <poll.h>
  49 .sp
  50 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
  51 .sp
  52 .BR "#define _GNU_SOURCE" "         /* feature_test_macros(7) 参照 */"
  53 .B #include <poll.h>
  54 .sp
  55 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
  56 .BI "        const struct timespec *" timeout_ts ", const sigset_t *" sigmask );
  57 .fi
  58 .SH 説明
  59 .BR poll ()
  60 は
  61 .BR select (2)
  62 と同様の仕事を行う、つまり、ファイルディスクリプタ集合のいずれか一つが
  63 I/O を実行可能な状態になるのを待つ。
  64
  65 監視するファイルディスクリプタ集合は、
  66 .I fds
  67 引き数で指定する。
  68 .I fds
  69 は、以下の型の構造体の配列である。
  70 .in +4n
  71 .nf
  72
  73 struct pollfd {
  74     int   fd;         /* file descriptor */
  75     short events;     /* requested events */
  76     short revents;    /* returned events */
  77 };
  78 .in
  79 .fi
  80 .PP
  81 .I nfds
  82 には、
  83 .I fds
  84 配列の要素数を指定する。
  85
  86 構造体の
  87 .I fd
  88 にはオープンしたファイルのファイルディスクリプタを入れる。
  89
  90 構造体の
  91 .I events
  92 要素は入力パラメータで、アプリケーションが興味を持っているイベントの
  93 ビットマスクを指定する。
  94
  95 .I revents
  96 要素は出力パラメータで、実際に起こったイベントがカーネルにより設定される。
  97 .I revents
  98 で返されるビット列には、
  99 .I events
 100 で指定したもののどれか、もしくは
 101 .BR POLLERR ,
 102 .BR POLLHUP ,
 103 .B POLLNVAL
 104 のうちの一つが含まれる
 105 .RB ( POLLERR ,
 106 .BR POLLHUP ,
 107 .B POLLNVAL
 108 の 3つのビットは
 109 .I events
 110 に指定しても意味がなく、対応した状態が真の場合に
 111 .I revents
 112 に設定される)。
 113
 114 どのファイルディスクリプタにも要求したイベントが発生しておらず、
 115 エラーも起こらない場合、
 116 .BR poll ()
 117 はイベントのうちいずれか一つが発生するまで停止 (block) する。
 118
 119 .I timeout
 120 引き数は
 121 .BR poll ()
 122 が停止する時間の上限を設定するもので、ミリ秒単位で指定する。
 123 .I timeout
 124 に負の値を指定すると、タイムアウト時間が無限となる。
 125
 126 .I events
 127 に指定したり、
 128 .I revents
 129 で返されるビットは \fI<poll.h>\fP で定義されている:
 130 .RS
 131 .TP
 132 .B POLLIN
 133 読み出し可能なデータがある。
 134 .TP
 135 .B POLLPRI
 136 読み出し可能な緊急データ (urgent data) がある
 137 (例えば、TCP ソケットの帯域外 (out-of-band data) データを受信した場合や、
 138 パケットモードの擬似端末のマスタがスレーブ側の変化を見つけたとき)。
 139 .TP
 140 .B POLLOUT
 141 書き込みが停止 (block) しない状態である。
 142 .TP
 143 .BR POLLRDHUP " (Linux 2.6.17 以降)"
 144 ストリームソケットの他端が、コネクションを close したか、
 145 コネクションの書き込み側を shutdown した。
 146 この定義を有効にするには、
 147 (「どの」ヘッダファイルをインクルードするよりも前に)
 148 .B _GNU_SOURCE
 149 機能検査マクロを定義しなければならない。
 150 .TP
 151 .B POLLERR
 152 エラー状態 (出力の場合のみ)。
 153 .TP
 154 .B POLLHUP
 155 ハングアップした (出力の場合のみ)。
 156 .TP
 157 .B POLLNVAL
 158 不正な要求:
 159 .I fd
 160 がオープンされていない (出力の場合のみ)。
 161 .RE
 162 .PP
 163 .B _XOPEN_SOURCE
 164 を定義してコンパイルした場合には、以下の定義も行われる。
 165 ただし、上記のリストにあるビット以上の情報が得られる訳ではない。
 166 .RS
 167 .TP
 168 .B POLLRDNORM
 169 .B POLLIN
 170 と同じ。
 171 .TP
 172 .B POLLRDBAND
 173 優先帯域データ (priority band data) が読み出し可能である
 174 (普通は Linux では使用されない)。
 175 .\" POLLRDBAND is used in the DECnet protocol.
 176 .TP
 177 .B POLLWRNORM
 178 .B POLLOUT
 179 と同じ。
 180 .TP
 181 .B POLLWRBAND
 182 優先帯域データ (priority data) が書き込み可能である。
 183 .RE
 184 .PP
 185 Linux では
 186 .B POLLMSG
 187 も定義されているが、使用されていない。
 188 .SS ppoll()
 189 .BR poll ()
 190 と
 191 .BR ppoll ()
 192 の関係は
 193 .BR select (2)
 194 と
 195 .BR pselect (2)
 196 の関係と同じようなものである:
 197 .BR pselect (2)
 198 と同様に、
 199 .BR ppoll ()
 200 を使うと、アプリケーションはファイルディスクリプタの状態変化
 201 もしくはシグナルの捕捉を安全に待つことができる。
 202 .PP
 203 .I timeout
 204 引き数の精度の違いを除くと、以下の
 205 .BR ppoll ()
 206 の呼び出しは、
 207 .nf
 208
 209     ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
 210
 211 .fi
 212 次のコールを
 213 .I atomic
 214 に実行するのと等価である。
 215 .nf
 216
 217     sigset_t origmask;
 218     int timeout;
 219
 220     timeout = (timeout_ts == NULL) ? \-1 :
 221               (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
 222     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 223     ready = poll(&fds, nfds, timeout);
 224     sigprocmask(SIG_SETMASK, &origmask, NULL);
 225 .fi
 226 .PP
 227 なぜ
 228 .BR ppoll ()
 229 が必要なのかについての説明は
 230 .BR pselect (2)
 231 の説明を参照のこと。
 232
 233 .I sigmask
 234 引き数に NULL が指定された場合、シグナルマスクの操作は行われない
 235 (したがって、
 236 .BR ppoll ()
 237 の
 238 .BR poll ()
 239 との違いは
 240 .I timeout
 241 引き数の精度だけとなる)。
 242
 243 .I timeout
 244 引き数は
 245 .BR ppoll ()
 246 が停止する時間の上限を指定するものである。
 247 この引き数には以下の型の構造体へのポインタを指定する。
 248 .in +4n
 249 .nf
 250
 251 struct timespec {
 252     long    tv_sec;         /* seconds */
 253     long    tv_nsec;        /* nanoseconds */
 254 };
 255 .fi
 256 .in
 257
 258 .I timeout_ts
 259 に NULL が指定された場合、
 260 .B ppoll
 261 は無限に停止することがあり得る。
 262 .SH 返り値
 263 成功した場合は正の数を返す。この数は 0 以外の
 264 .I revents
 265 要素を持つ構造体の数である (別の言い方をすると、これらのディスクリプタ
 266 にはイベントかエラー報告がある)。
 267 値 0 は、タイムアウトとなり、どのファイルディスクリプタでもイベントが
 268 発生しなかったことを示す。エラーの場合は \-1 が返され、
 269 .I errno
 270 が適切に設定される。
 271 .SH エラー
 272 .TP
 273 .B EFAULT
 274 引き数として指定した配列が、呼び出したプロセスのアドレス空間に
 275 含まれていない。
 276 .TP
 277 .B EINTR
 278 要求されたイベントのどれかが起こる前にシグナルが発生した。
 279 .BR signal (7)
 280 参照。
 281 .TP
 282 .B EINVAL
 283 .I nfds
 284 の値が
 285 .B RLIMIT_NOFILE
 286 を超えた。
 287 .TP
 288 .B ENOMEM
 289 ファイルディスクリプタ・テーブルを確保するためのメモリがない。
 290 .SH バージョン
 291 .BR poll ()
 292 システムコールは Linux 2.1.23 で導入された。
 293 .BR poll ()
 294 ライブラリ・コールは libc 5.4.28 から導入された
 295 (これはカーネルが
 296 .BR poll ()
 297 システムコールをサポートしていない場合に
 298 .BR select (2)
 299 を使用してエミュレートを行う)。
 300
 301 .BR ppoll ()
 302 システムコールは カーネル 2.6.16 で Linux に追加された。
 303 .BR ppoll ()
 304 ライブラリコールは glibc 2.4 に追加された。
 305 .SH 準拠
 306 .BR poll ()
 307 は POSIX.1-2001 に準拠している。
 308 .BR ppoll ()
 309 は Linux 固有である。
 310 .\" NetBSD 3.0 には pollts() がある。
 311 .\" pollts() は Linux ppoll () と同じようなものである。
 312 .SH 注意
 313 いくつかの実装では、値 \-1 を持った非標準の定数
 314 .B INFTIM
 315 が定義されており、
 316 .BR poll ()
 317 の
 318 .I timeout
 319 の指定に使用できる。
 320 この定数は glibc では定義されていない。
 321 .SS "Linux での注意"
 322 Linux の
 323 .BR ppoll ()
 324 システムコールは
 325 .I timeout_ts
 326 引き数を変更する。
 327 しかし、glibc のラッパー関数は、システムコールに渡す timeout 引き数
 328 としてローカル変数を使うことでこの動作を隠蔽している。
 329 このため、glibc の
 330 .BR ppoll ()
 331 関数では
 332 .I timeout_ts
 333 引き数は変更されない。
 334 .SH バグ
 335 .BR select (2)
 336 の「バグ」の節に書かれている、誤った準備完了通知 (spurious readiness
 337 notifications) についての議論を参照のこと。
 338 .SH 関連項目
 339 .BR select (2),
 340 .BR select_tut (2),
 341 .BR time (7)