release/man2/poll.2

   1 .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
   2 .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  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 .\"*******************************************************************
  32 .\"
  33 .\" This file was generated with po4a. Translate the source file.
  34 .\"
  35 .\"*******************************************************************
  36 .\"
  37 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  38 .\"         all rights reserved.
  39 .\" Translated 1997-12-11, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  40 .\" Updated & Modified 2004-05-22, Yuichi SATO <ysato444@yahoo.co.jp>
  41 .\" Updated & Modified 2005-01-03, Yuichi SATO
  42 .\" Updated & Modified 2005-10-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  43 .\" Updated 2005-12-05, Akihiro MOTOKI, Catch up to LDP man-pages 2.16
  44 .\" Updated 2006-04-16, Akihiro MOTOKI, Catch up to LDP man-pages 2.28
  45 .\" Updated 2006-07-23, Akihiro MOTOKI, Catch up to LDP man-pages 2.36
  46 .\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
  47 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  48 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  49 .\"
  50 .TH POLL 2 2014\-01\-31 Linux "Linux Programmer's Manual"
  51 .SH 名前
  52 poll, ppoll \- ファイルディスクリプタにおけるイベントを待つ
  53 .SH 書式
  54 .nf
  55 \fB#include <poll.h>\fP
  56 .sp
  57 \fBint poll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, int \fP\fItimeout\fP\fB);\fP
  58 .sp
  59 \fB#define _GNU_SOURCE\fP         /* feature_test_macros(7) 参照 */
  60 \fB#include <poll.h>\fP
  61 .sp
  62 \fBint ppoll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, \fP
  63 \fB        const struct timespec *\fP\fItimeout_ts\fP\fB, const sigset_t *\fP\fIsigmask\fP\fB);\fP
  64 .fi
  65 .SH 説明
  66 \fBpoll\fP()  は \fBselect\fP(2)  と同様の仕事を行う、つまり、ファイルディスクリプタ集合のいずれか一つが I/O
  67 を実行可能な状態になるのを待つ。
  68
  69 監視するファイルディスクリプタ集合は、 \fIfds\fP 引き数で指定する。 \fIfds\fP は、以下の型の構造体の配列である。
  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 \fInfds\fP には、 \fIfds\fP 配列の要素数を指定する。
  82
  83 \fIfd\fP フィールドには、オープンされたファイルのファイルディスクリプタが入る。
  84 このフィールドが負の場合、対応する \fIevents\fP フィールドは無視され、
  85 \fIrevents\fP には 0 が返される。(この機能により、一つの \fBpoll\fP() の呼び出しで
  86 簡単にあるファイルディスクリプタを無視することができる。
  87 単に \fIfd\fP フィールドの符号を反転するだけでよい。)
  88
  89 構造体の \fIevents\fP 要素は入力パラメータで、 ファイルディスクリプタ \fIfd\fP に関して、
  90 アプリケーションが興味を持っているイベントのビットマスクを指定する。 このフィールドには 0 を指定することもでき、 その場合 \fIrevents\fP
  91 で返されるイベントは \fBPOLLHUP\fP, \fBPOLLERR\fP, \fBPOLLNVAL\fP だけである (下記参照)。
  92
  93 \fIrevents\fP 要素は出力パラメータで、実際に起こったイベントがカーネルにより設定される。 \fIrevents\fP で返されるビット列には、
  94 \fIevents\fP で指定したもののどれか、もしくは \fBPOLLERR\fP, \fBPOLLHUP\fP, \fBPOLLNVAL\fP のうちの一つが含まれる
  95 (\fBPOLLERR\fP, \fBPOLLHUP\fP, \fBPOLLNVAL\fP の 3つのビットは \fIevents\fP
  96 に指定しても意味がなく、対応した状態が真の場合に \fIrevents\fP に設定される)。
  97
  98 どのファイルディスクリプタにも要求したイベントが発生しておらず、 エラーも起こらない場合、 \fBpoll\fP()
  99 はイベントのうちいずれか一つが発生するまで停止 (block) する。
 100
 101 \fItimeout\fP 引き数は、 ファイルディスクリプタが利用可能になるまで \fBpoll\fP() が停止する時間をミリ秒で指定する。 \fBpoll\fP()
 102 の呼び出しは以下のいずれかになるまで停止する。
 103 .IP * 3
 104 ファイルディスクリプタが利用可能になる
 105 .IP *
 106 呼び出しがシグナルハンドラーにより割り込まれた
 107 .IP *
 108 タイムアウトが満了する
 109 .PP
 110 \fItimeout\fP 時間はシステムクロックの粒度に切り上げられ、 カーネルのスケジューリング遅延により少しだけ長くなる可能性がある点に注意すること。
 111 \fItimeout\fP に負の値を指定した場合、タイムアウト時間が無限大を意味する。 \fItimeout\fP を 0 に指定した場合、I/O
 112 可能なファイルディスクリプタがない場合であっても、 \fBpoll\fP() はすぐに返る。
 113
 114 \fIevents\fP に指定したり、 \fIrevents\fP で返されるビットは \fI<poll.h>\fP で定義されている:
 115 .RS
 116 .TP
 117 \fBPOLLIN\fP
 118 読み出し可能なデータがある。
 119 .TP
 120 \fBPOLLPRI\fP
 121 読み出し可能な緊急データ (urgent data) がある (例えば、TCP ソケットの帯域外 (out\-of\-band data)
 122 データを受信した場合や、 パケットモードの擬似端末のマスタがスレーブ側の変化を見つけたとき)。
 123 .TP
 124 \fBPOLLOUT\fP
 125 書き込みが停止 (block) しない状態である。
 126 .TP
 127 \fBPOLLRDHUP\fP (Linux 2.6.17 以降)
 128 ストリームソケットの他端が、コネクションを close したか、 コネクションの書き込み側を shutdown した。 この定義を有効にするには、
 129 (「どの」ヘッダファイルをインクルードするよりも前に)  \fB_GNU_SOURCE\fP 機能検査マクロを定義しなければならない。
 130 .TP
 131 \fBPOLLERR\fP
 132 エラー状態 (出力の場合のみ)。
 133 .TP
 134 \fBPOLLHUP\fP
 135 ハングアップした (出力の場合のみ)。
 136 .TP
 137 \fBPOLLNVAL\fP
 138 不正な要求: \fIfd\fP がオープンされていない (出力の場合のみ)。
 139 .RE
 140 .PP
 141 \fB_XOPEN_SOURCE\fP を定義してコンパイルした場合には、以下の定義も行われる。
 142 ただし、上記のリストにあるビット以上の情報が得られる訳ではない。
 143 .RS
 144 .TP
 145 \fBPOLLRDNORM\fP
 146 \fBPOLLIN\fP と同じ。
 147 .TP
 148 \fBPOLLRDBAND\fP
 149 .\" POLLRDBAND is used in the DECnet protocol.
 150 優先帯域データ (priority band data) が読み出し可能である (普通は Linux では使用されない)。
 151 .TP
 152 \fBPOLLWRNORM\fP
 153 \fBPOLLOUT\fP と同じ。
 154 .TP
 155 \fBPOLLWRBAND\fP
 156 優先帯域データ (priority data) が書き込み可能である。
 157 .RE
 158 .PP
 159 Linux では \fBPOLLMSG\fP も定義されているが、使用されていない。
 160 .SS ppoll()
 161 \fBpoll\fP()  と \fBppoll\fP()  の関係は \fBselect\fP(2)  と \fBpselect\fP(2)  の関係と同じようなものである:
 162 \fBpselect\fP(2)  と同様に、 \fBppoll\fP()  を使うと、アプリケーションはファイルディスクリプタの状態変化
 163 もしくはシグナルの捕捉を安全に待つことができる。
 164 .PP
 165 \fItimeout\fP 引き数の精度の違いを除くと、以下の \fBppoll\fP()  の呼び出しは、
 166 .nf
 167
 168     ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
 169
 170 .fi
 171 次の呼び出しを \fIatomic\fP に実行するのと等価である。
 172 .nf
 173
 174     sigset_t origmask;
 175     int timeout;
 176
 177     timeout = (timeout_ts == NULL) ? \-1 :
 178               (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
 179     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 180     ready = poll(&fds, nfds, timeout);
 181     sigprocmask(SIG_SETMASK, &origmask, NULL);
 182 .fi
 183 .PP
 184 なぜ \fBppoll\fP()  が必要なのかについての説明は \fBpselect\fP(2)  の説明を参照のこと。
 185
 186 \fIsigmask\fP 引き数に NULL が指定された場合、シグナルマスクの操作は行われない (したがって、 \fBppoll\fP()  の
 187 \fBpoll\fP()  との違いは \fItimeout\fP 引き数の精度だけとなる)。
 188
 189 \fItimeout\fP 引き数は \fBppoll\fP()  が停止する時間の上限を指定するものである。
 190 この引き数には以下の型の構造体へのポインタを指定する。
 191 .in +4n
 192 .nf
 193
 194 struct timespec {
 195     long    tv_sec;         /* seconds */
 196     long    tv_nsec;        /* nanoseconds */
 197 };
 198 .fi
 199 .in
 200
 201 \fItimeout_ts\fP に NULL が指定された場合、 \fBppoll\fP は無限に停止することがあり得る。
 202 .SH 返り値
 203 成功した場合は正の数を返す。この数は 0 以外の \fIrevents\fP 要素を持つ構造体の数である (別の言い方をすると、これらのディスクリプタ
 204 にはイベントかエラー報告がある)。 値 0 は、タイムアウトとなり、どのファイルディスクリプタでもイベントが 発生しなかったことを示す。エラーの場合は
 205 \-1 が返され、 \fIerrno\fP が適切に設定される。
 206 .SH エラー
 207 .TP
 208 \fBEFAULT\fP
 209 引き数として指定した配列が、呼び出したプロセスのアドレス空間に 含まれていない。
 210 .TP
 211 \fBEINTR\fP
 212 要求されたイベントのどれかが起こる前にシグナルが発生した。 \fBsignal\fP(7)  参照。
 213 .TP
 214 \fBEINVAL\fP
 215 \fInfds\fP の値が \fBRLIMIT_NOFILE\fP を超えた。
 216 .TP
 217 \fBENOMEM\fP
 218 ファイルディスクリプタ・テーブルを確保するためのメモリがない。
 219 .SH バージョン
 220 .\" library call was introduced in libc 5.4.28
 221 \fBpoll\fP() システムコールは Linux 2.1.23 で導入された。
 222 このシステムコールが存在しない古いカーネルでは、
 223 glibc (や古い Linux libc) は \fBselect\fP(2) を使用して \fBpoll\fP()
 224 ラッパー関数のエミュレーションを行う。
 225
 226 \fBppoll\fP()  システムコールは カーネル 2.6.16 で Linux に追加された。 \fBppoll\fP()  ライブラリコールは glibc
 227 2.4 に追加された。
 228 .SH 準拠
 229 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
 230 \fBpoll\fP()  は POSIX.1\-2001 に準拠している。 \fBppoll\fP()  は Linux 固有である。
 231 .SH 注意
 232 いくつかの実装では、値 \-1 を持った非標準の定数 \fBINFTIM\fP が定義されており、 \fBpoll\fP()  の \fItimeout\fP
 233 の指定に使用できる。 この定数は glibc では定義されていない。
 234
 235 \fBpoll\fP() で監視中のファイルディスクリプタが別のスレッドによってクローズされた場合に何が起こるかの議論については、 \fBselect\fP(2)
 236 を参照してほしい。
 237 .SS "Linux での注意"
 238 Linux の \fBppoll\fP()  システムコールは \fItimeout_ts\fP 引き数を変更する。 しかし、glibc
 239 のラッパー関数は、システムコールに渡す timeout 引き数 としてローカル変数を使うことでこの動作を隠蔽している。 このため、glibc の
 240 \fBppoll\fP()  関数では \fItimeout_ts\fP 引き数は変更されない。
 241 .SH バグ
 242 \fBselect\fP(2)  の「バグ」の節に書かれている、誤った準備完了通知 (spurious readiness notifications)
 243 についての議論を参照のこと。
 244 .SH 関連項目
 245 \fBrestart_syscall\fP(2), \fBselect\fP(2), \fBselect_tut\fP(2), \fBtime\fP(7)
 246 .SH この文書について
 247 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 248 である。プロジェクトの説明とバグ報告に関する情報は
 249 http://www.kernel.org/doc/man\-pages/ に書かれている。