release/man2/select.2

   1 .\" This manpage is copyright (C) 1992 Drew Eckhardt,
   2 .\"                 copyright (C) 1995 Michael Shields.
   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 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  27 .\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
  28 .\" Sun Feb 11 14:07:00 MET 1996  Martin Schulze  <joey@linux.de>
  29 .\"     * layout slightly modified
  30 .\"
  31 .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  32 .\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb
  33 .\" Modified Thu Feb  9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb
  34 .\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net>
  35 .\" 2005-03-11, mtk, modified pselect() text (it is now a system
  36 .\"     call in 2.6.16.
  37 .\"
  38 .\"*******************************************************************
  39 .\"
  40 .\" This file was generated with po4a. Translate the source file.
  41 .\"
  42 .\"*******************************************************************
  43 .TH SELECT 2 2012\-08\-17 Linux "Linux Programmer's Manual"
  44 .SH 名前
  45 select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- 同期 I/O の多重化
  46 .SH 書式
  47 .nf
  48 /* POSIX.1\-2001 に従う場合 */
  49 .br
  50 \fB#include <sys/select.h>\fP
  51 .sp
  52 /* 以前の規格に従う場合 */
  53 .br
  54 \fB#include <sys/time.h>\fP
  55 .br
  56 \fB#include <sys/types.h>\fP
  57 .br
  58 \fB#include <unistd.h>\fP
  59 .sp
  60 \fBint select(int \fP\fInfds\fP\fB, fd_set *\fP\fIreadfds\fP\fB, fd_set *\fP\fIwritefds\fP\fB,\fP
  61 \fB           fd_set *\fP\fIexceptfds\fP\fB, struct timeval *\fP\fItimeout\fP\fB);\fP
  62 .sp
  63 \fBvoid FD_CLR(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
  64 .br
  65 \fBint  FD_ISSET(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
  66 .br
  67 \fBvoid FD_SET(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
  68 .br
  69 \fBvoid FD_ZERO(fd_set *\fP\fIset\fP\fB);\fP
  70 .sp
  71 \fB#include <sys/select.h>\fP
  72 .sp
  73 \fBint pselect(int \fP\fInfds\fP\fB, fd_set *\fP\fIreadfds\fP\fB, fd_set *\fP\fIwritefds\fP\fB,\fP
  74 \fB            fd_set *\fP\fIexceptfds\fP\fB, const struct timespec *\fP\fItimeout\fP\fB,\fP
  75 \fB            const sigset_t *\fP\fIsigmask\fP\fB);\fP
  76 .fi
  77 .sp
  78 .in -4n
  79 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  80 .in
  81 .sp
  82 \fBpselect\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  83 .SH 説明
  84 \fBselect\fP()  や \fBpselect\fP()  を使うと、プログラムで複数のファイルディスクリプタを監視し、
  85 一つ以上のファイルディスクリプタがある種の I/O 操作の 「ready (準備ができた)」状態 (例えば、読み込み可能になった状態)
  86 になるまで待つことができる。 ファイルディスクリプタが ready (準備ができた) とは、 対応する I/O 操作 (例えば \fBread\fP(2)
  87 など) が停止 (block) なしに実行可能な状態にあることを意味する。
  88 .PP
  89 The operation of \fBselect\fP()  and \fBpselect\fP()  is identical, other than
  90 these three differences:
  91 .TP
  92 (i)
  93 \fBselect\fP()  では、タイムアウト時間の指定に構造体 \fIstruct timeval\fP (秒・マイクロ秒単位) を用いる。 一方、
  94 \fBpselect\fP()  関数では、構造体 \fIstruct timespec\fP (秒・ナノ秒単位) を用いる。
  95 .TP
  96 (ii)
  97 \fBselect\fP()  は残り時間を示す \fItimeout\fP 引き数を更新することがある。 \fBpselect\fP()  はこの引き数を変更しない。
  98 .TP
  99 (iii)
 100 \fBselect\fP()  は \fIsigmask\fP 引き数を持たない。その動作は \fIsigmask\fP に NULL を指定した場合の
 101 \fBpselect\fP()  と同じである。
 102 .PP
 103 3 つの独立したファイルディスクリプタ集合の監視を行う。 \fIreadfds\fP に入れられたディスクリプタについては、読み込みが可能かどうかを 監視する
 104 (より正確にいうと、停止 (block) なしで読むことができるかを 調べる。ファイルの終端 (end\-of\-file) の場合も、
 105 ファイルディスクリプタは読み込み可能として扱われる)。 \fIwritefds\fP に入れられたディスクリプタについては、停止せずに書き込みが
 106 可能かどうかを監視する。 \fIexceptfds\fP にあるものについては、例外の監視を行なう。システムコール終了時に、
 107 どのファイルディスクリプタの状態が実際に変化したか示すために、 集合の内容が変更される。
 108 ある種別のイベントを監視したいファイルディスクリプタが一つもない場合には、 対応するファイルディスクリプタ集合に NULL を指定することができる。
 109 .PP
 110 集合を操作するために 4 つのマクロが提供されている。 \fBFD_ZERO\fP()  は集合を消去する。 \fBFD_SET\fP()  と
 111 \fBFD_CLR\fP()  はそれぞれ指定したファイルディスクリプタの集合への追加、削除を行う。 \fBFD_ISSET\fP()
 112 は集合にファイルディスクリプタがあるかどうか調べる; このマクロは \fBselect\fP()  が終了した後に使うと便利である。
 113 .PP
 114 \fInfds\fP は 3 つの集合に含まれるファイルディスクリプタの最大値に 1 を足したものである。
 115 .PP
 116 \fItimeout\fP 引き数で、ファイルディスクリプタが ready になるのを待って
 117 \fBselect\fP() が停止する最小の停止時間を指定する
 118 (この停止時間はシステムクロックの粒度に切り上げられ、
 119 カーネルのスケジューリング遅延により少しだけ長くなる可能性がある)。
 120 \fItimeval\fP 構造体の両方のフィールドが 0 の場合、 \fBselect\fP() はすぐに復
 121 帰する (この機能はポーリング (polling) を行うのに便利である)。
 122 \fItimeout\fP に NULL (タイムアウトなし) が指定されると、 \fBselect\fP() は無
 123 期限に停止 (block) する。
 124 .PP
 125 \fIsigmask\fP は、シグナルマスク (\fBsigprocmask\fP(2)  を参照) へのポインタである。 \fIsigmask\fP が NULL
 126 でない場合、 \fBpselect\fP()  は \fIsigmask\fP が指しているシグナルマスクで現在のシグナルマスクを置き換えてから、 "select"
 127 関数を実行し、 終了後にシグナルマスクを元のシグナルマスクに戻す。
 128 .PP
 129 \fItimeout\fP 引き数の精度の違いを除くと、以下の \fBpselect\fP()  の呼び出しは、
 130 .nf
 131
 132     ready = pselect(nfds, &readfds, &writefds, &exceptfds,
 133                     timeout, &sigmask);
 134
 135 .fi
 136 次のコールを \fIatomic\fP に実行するのと等価である。
 137 .nf
 138
 139     sigset_t origmask;
 140
 141     pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
 142     ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
 143     pthread_sigmask(SIG_SETMASK, &origmask, NULL);
 144 .fi
 145 .PP
 146 \fBpselect\fP()  が必要になる理由は、シグナルやファイルディスクリプタの状態変化を 待ちたいときには、競合状態を避けるために atomic
 147 なテストが必要になる からである。 (シグナルハンドラが大域フラグを設定して戻る場合を考えてみよう。 この大域フラグのテストに続けて
 148 \fBselect\fP()  を呼び出すと、 シグナルがテストの直後かつ呼び出しの直前に届いた時には \fBselect\fP()
 149 は永久にハングしてしまうかもしれない。 一方、 \fBpselect\fP()  を使うと、まずシグナルを禁止 (block)
 150 して、入ってくるシグナルを操作し、 望みの \fIsigmask\fP で \fBpselect\fP()  を呼び出すことで、前記の競合を避けることができる。)
 151 .SS タイムアウト
 152 これらの関数で使用される時間関連の構造体は、 \fI<sys/time.h>\fP で
 153
 154 .in +4n
 155 .nf
 156 struct timeval {
 157     long    tv_sec;         /* 秒 */
 158     long    tv_usec;        /* マイクロ秒 */
 159 };
 160 .fi
 161 .in
 162
 163 や
 164
 165 .in +4n
 166 .nf
 167 struct timespec {
 168     long    tv_sec;         /* 秒 */
 169     long    tv_nsec;        /* ナノ秒 */
 170 };
 171 .fi
 172 .in
 173
 174 のように定義されている。 (POSIX.1\-2001 での定義については下記の「注意」を参照)
 175 .PP
 176 秒単位以下の精度でスリープを実現する 移植性の高い方法として、 3 つの集合全てを空、 \fInfds\fP を 0 、 \fItimeout\fP を NULL
 177 でない値に設定して \fBselect\fP()  を呼び出すという方法を使っているコードもある。
 178 .PP
 179 .\" .PP - it is rumored that:
 180 .\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
 181 .\" - it is certainly true that:
 182 .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
 183 Linux では、 \fBselect\fP()  は \fItimeout\fP を変更し、残りの停止時間を反映するようになっているが、
 184 他のほとんどの実装ではこのようになっていない (POSIX.1\-2001 はどちらの動作も認めている)。 このため、 \fItimeout\fP
 185 を参照している Linux のコードを他のオペレーティング・システムへ 移植する場合、問題が起こる。 また、ループの中で \fItimeval\fP
 186 構造体を初期化せずにそのまま再利用して \fBselect\fP()  を複数回行なっているコードを Linux へ移植する場合にも、問題が起こる。
 187 \fBselect\fP()  から復帰した後は \fItimeout\fP は未定義であると考えるべきである。
 188 .SH 返り値
 189 成功した場合、 \fBselect\fP()  と \fBpselect\fP()  は更新された 3 つのディスクリプタ集合に含まれている
 190 ファイルディスクリプタの数 (つまり、 \fIreadfds\fP, \fIwritefds\fP, \fIexceptfds\fP 中の 1 になっているビットの総数)
 191 を返す。 何も起こらずに時間切れになった場合、 ディスクリプタの数は 0 になることもある。 エラーならば \-1 を返し、 \fIerrno\fP
 192 に適切な値が設定される; 集合と \fItimeout\fP は未定義となるので、エラーが起こった後はそれらの内容を信頼してはならない。
 193 .SH エラー
 194 .TP
 195 \fBEBADF\fP
 196 いずれかの集合に無効なファイルディスクリプタが指定された (おそらくは、すでにクローズされたファイルディスクリプタか、
 197 エラーが発生したファイルディスクリプタが指定された)。
 198 .TP
 199 \fBEINTR\fP
 200 シグナルを受信した。
 201 .TP
 202 \fBEINVAL\fP
 203 \fIn\fP が負、または \fItimeout\fP に入っている値が不正である。
 204 .TP
 205 \fBENOMEM\fP
 206 内部テーブルにメモリを割り当てることができなかった。
 207 .SH バージョン
 208 \fBpselect\fP()  はカーネル 2.6.16 で Linux に追加された。 それ以前は、 \fBpselect\fP()  は glibc
 209 でエミュレートされていた (「バグ」の章を参照)。
 210 .SH 準拠
 211 \fBselect\fP()  は POSIX.1\-2001 と 4.4BSD (\fBselect\fP()  は 4.2BSD で最初に登場した) に準拠する。
 212 BSD ソケット層のクローンをサポートしている非 BSD システム (System V 系も含む) との間でだいたい移植性がある。しかし System
 213 V 系では たいがい timeout 変数を exit の前にセットするが、 BSD 系ではそうでないので注意すること。
 214 .PP
 215 \fBpselect\fP()  は POSIX.1g と POSIX.1\-2001 で定義されている。
 216 .SH 注意
 217 \fIfd_set\fP は固定サイズのバッファである。 負や \fBFD_SETSIZE\fP 以上の値を持つ \fIfd\fP に対して \fBFD_CLR\fP()  や
 218 \fBFD_SET\fP()  を実行した場合、 どのような動作をするかは定義されていない。 また、 POSIX では \fIfd\fP
 219 は有効なファイルディスクリプタでなければならないと規定されている。
 220
 221 型宣言に関しては、昔ながらの状況では \fItimeval\fP 構造体の 2 つのフィールドは (上記のように) 両方とも \fIlong\fP
 222 型であり、構造体は \fI<sys/time.h>\fP で定義されている。 POSIX.1\-2001 の下では、以下のようになっている。
 223
 224 .in +4n
 225 .nf
 226 struct timeval {
 227          time_t         tv_sec;     /* 秒 */
 228          suseconds_t    tv_usec;    /* マイクロ秒 */
 229 };
 230 .fi
 231 .in
 232
 233 この構造体は \fI<sys/select.h>\fP で定義されており、データ型 \fItime_t\fP と \fIsuseconds_t\fP は
 234 \fI<sys/types.h>\fP で定義されている。
 235 .LP
 236 プロトタイプに関しては、昔ながらの状況で \fBselect\fP()  を使いたい場合は、 \fI<time.h>\fP
 237 をインクルードすればよい。 POSIX.1\-2001 の環境で \fBselect\fP()  と \fBpselect\fP()  を使いたい場合は、
 238 \fI<sys/select.h>\fP をインクルードすればよい。
 239
 240 ヘッダファイル \fI<sys/select.h>\fP は libc4 と libc5 にはなく、glibc 2.0 以降に存在する。
 241 悪いことに glibc 2.0 以前では \fBpselect\fP()  のプロトタイプが間違っている。 glibc 2.1 から 2.2.1 では
 242 \fB_GNU_SOURCE\fP が定義されている場合に、 \fBpselect\fP()  が提供される。 glibc 2.2.2 以降では、
 243 \fBpselect\fP()  を使用するには、「書式」に記載された要件を満たす必要がある。
 244 .SS "Multithreaded applications"
 245 If a file descriptor being monitored by \fBselect\fP()  is closed in another
 246 thread, the result is unspecified.  On some UNIX systems, \fBselect\fP()
 247 unblocks and returns, with an indication that the file descriptor is ready
 248 (a subsequent I/O operation will likely fail with an error, unless another
 249 the file descriptor reopened between the time \fBselect\fP()  returned and the
 250 I/O operations was performed).  On Linux (and some other systems), closing
 251 the file descriptor in another thread has no effect on \fBselect\fP().  In
 252 summary, any application that relies on a particular behavior in this
 253 scenario must be considered buggy.
 254 .SS "Linux notes"
 255 The \fBpselect\fP()  interface described in this page is implemented by glibc.
 256 The underlying Linux system call is named \fBpselect6\fP().  This system call
 257 has somewhat different behavior from the glibc wrapper function.
 258
 259 Linux の \fBpselect6\fP() システムコールは \fItimeout\fP 引き数を変更する。
 260 しかし、glibc のラッパー関数は、システムコールに渡す timeout 引き数と
 261 してローカル変数を使うことでこの動作を隠蔽している。このため、glibc の
 262 \fBpselect\fP() 関数は \fItimeout\fP 引き数を変更しない。
 263 これが POSIX.1\-2001 が要求している動作である。
 264
 265 The final argument of the \fBpselect6\fP()  system call is not a \fIsigset_t\ *\fP
 266 pointer, but is instead a structure of the form:
 267 .in +4
 268 .nf
 269
 270 struct {
 271     const sigset_t *ss;     /* シグナル集合へのポインタ */
 272     size_t          ss_len; /* 'ss' が指すオブジェクトのサイズ
 273                                (バイト数) */
 274 };
 275
 276 .fi
 277 .in
 278 このようにすることで、ほとんどのアーキテクチャがサポートしている
 279 システムコールの引き数が最大で 6 個という事実を満たしつつ、
 280 \fBpselect6\fP() システムコールがシグナル集合へのポインタとシグナル集合
 281 のサイズの両方を取得することができるのである。
 282 .SH バグ
 283 glibc 2.0 では、 \fIsigmask\fP 引き数を取らないバージョンの \fBpselect\fP()  が提供されていた。
 284
 285 バージョン 2.1 以降の glibc では、 \fBpselect\fP()  は \fBsigprocmask\fP(2)  と \fBselect\fP()
 286 を使ってエミュレートされていた。 この実装にはきわどい競合条件において脆弱性が残っていた。 この競合条件における問題を防止するために
 287 \fBpselect\fP()  は設計されたのである。 最近のバージョンの glibc では、カーネルがサポートしている場合には、 (競合が起こらない)
 288 \fBpselect\fP()  システムコールが使用される。
 289
 290 \fBpselect\fP() がないシステムにおいて、シグナルの捕捉を信頼性があり (移植
 291 性も高い) 方法で行うには、 自己パイプ (self\-pipe) という技を使うとよい。
 292 この方法では、シグナルハンドラはパイプへ 1 バイトのデータを書き込み、
 293 同じパイプのもう一端をメインプログラムの \fBselect\fP() で監視する (一杯に
 294 なったパイプへの書き込みや空のパイプから読み出しを行った際に起こるであ
 295 ろう停止 (blocking) を避けるためには、パイプへの読み書きの際には 非停止
 296 (nonblocking) I/O を使用するとよい)。
 297
 298 .\" Stevens discusses a case where accept can block after select
 299 .\" returns successfully because of an intervening RST from the client.
 300 .\" Maybe the kernel should have returned EIO in such a situation?
 301 Linux では、 \fBselect\fP()  がソケットファイルディスクリプタで "読み込みの準備ができた" と報告した場合でも、 この後で read
 302 を行うと停止 (block) することがある。このような状況は、 例えば、データが到着したが、検査でチェックサム異常が見つかり廃棄された時
 303 などに起こりえる。他にもファイルディスクリプタが準備できたと間違って 報告される状況が起こるかもしれない。
 304 したがって、停止すべきではないソケットに対しては \fBO_NONBLOCK\fP を使うとより安全であろう。
 305
 306 Linux では、 \fBselect\fP()  がシグナルハンドラにより割り込まれた場合 (つまり \fBEINTR\fP エラーが返る場合)、
 307 \fItimeout\fP も変更する。 これは POSIX.1\-2001 では認められていない挙動である。 Linux の \fBpselect\fP()
 308 システムコールも同じ挙動をするが、 glibc のラッパー関数がこの挙動を隠蔽している。 具体的には、glibc のラッパー関数の内部で、
 309 \fItimeout\fP をローカル変数にコピーし、 このローカル変数をシステムコールに渡している。
 310 .SH 例
 311 .nf
 312 #include <stdio.h>
 313 #include <stdlib.h>
 314 #include <sys/time.h>
 315 #include <sys/types.h>
 316 #include <unistd.h>
 317
 318 int
 319 main(void)
 320 {
 321     fd_set rfds;
 322     struct timeval tv;
 323     int retval;
 324
 325     /* stdin (fd 0) を監視し、入力があった場合に表示する。*/
 326     FD_ZERO(&rfds);
 327     FD_SET(0, &rfds);
 328
 329     /* 5 秒間監視する。*/
 330     tv.tv_sec = 5;
 331     tv.tv_usec = 0;
 332
 333     retval = select(1, &rfds, NULL, NULL, &tv);
 334     /* この時点での tv の値を信頼してはならない。*/
 335
 336     if (retval == \-1)
 337         perror("select()");
 338     else if (retval)
 339         printf("今、データが取得できました。\en");
 340         /* FD_ISSET(0, &rfds) が true になる。*/
 341     else
 342         printf("5 秒以内にデータが入力されませんでした。\en");
 343
 344     exit(EXIT_SUCCESS);
 345 }
 346 .fi
 347 .SH 関連項目
 348 \fBaccept\fP(2), \fBconnect\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBrecv\fP(2), \fBsend\fP(2),
 349 \fBsigprocmask\fP(2), \fBwrite\fP(2), \fBepoll\fP(7), \fBtime\fP(7)
 350
 351 考察と使用例の書かれたチュートリアルとして、 \fBselect_tut\fP(2)  がある。
 352 .SH この文書について
 353 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 354 である。プロジェクトの説明とバグ報告に関する情報は
 355 http://www.kernel.org/doc/man\-pages/ に書かれている。