Update README

[linuxjm/LDP_man-pages.git] / draft / man2 / select.2

.\" This manpage is copyright (C) 1992 Drew Eckhardt,
.\"                 copyright (C) 1995 Michael Shields.
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
.\" Sun Feb 11 14:07:00 MET 1996  Martin Schulze  <joey@linux.de>
.\"     * layout slightly modified
.\"
.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb
.\" Modified Thu Feb  9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb
.\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net>
.\" 2005-03-11, mtk, modified pselect() text (it is now a system
.\"     call in 2.6.16.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1997 HANATAKA Shinya all rights reserved.
.\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Modified 2000-03-12, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated & Modified 2001-06-04, Yuichi SATO <ysato@h4.dion.ne.jp>
.\" Updated & Modified 2001-07-01, Yuichi SATO
.\" Updated & Modifedd 2002-01-14, Yuichi SATO
.\" Updated 2002-09-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2003-01-19, Akihiro MOTOKI
.\" Updated 2005-03-17, Akihiro MOTOKI
.\" Updated 2006-04-16, Akihiro MOTOKI, LDP v2.28
.\" Updated 2006-07-23, Akihiro MOTOKI, LDP v2.36
.\" Updated 2007-09-08, Akihiro MOTOKI, LDP v2.64
.\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
.\" Updated 2012-05-30, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH SELECT 2 2015\-01\-22 Linux "Linux Programmer's Manual"
.SH 名前
select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- 同期 I/O の多重化
.SH 書式
.nf
/* POSIX.1\-2001 に従う場合 */
.br
\fB#include <sys/select.h>\fP
.sp
/* 以前の規格に従う場合 */
.br
\fB#include <sys/time.h>\fP
.br
\fB#include <sys/types.h>\fP
.br
\fB#include <unistd.h>\fP
.sp
\fBint select(int \fP\fInfds\fP\fB, fd_set *\fP\fIreadfds\fP\fB, fd_set *\fP\fIwritefds\fP\fB,\fP
\fB           fd_set *\fP\fIexceptfds\fP\fB, struct timeval *\fP\fItimeout\fP\fB);\fP
.sp
\fBvoid FD_CLR(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
.br
\fBint  FD_ISSET(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
.br
\fBvoid FD_SET(int \fP\fIfd\fP\fB, fd_set *\fP\fIset\fP\fB);\fP
.br
\fBvoid FD_ZERO(fd_set *\fP\fIset\fP\fB);\fP
.sp
\fB#include <sys/select.h>\fP
.sp
\fBint pselect(int \fP\fInfds\fP\fB, fd_set *\fP\fIreadfds\fP\fB, fd_set *\fP\fIwritefds\fP\fB,\fP
\fB            fd_set *\fP\fIexceptfds\fP\fB, const struct timespec *\fP\fItimeout\fP\fB,\fP
\fB            const sigset_t *\fP\fIsigmask\fP\fB);\fP
.fi
.sp
.in -4n
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.in
.sp
\fBpselect\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
.SH 説明
\fBselect\fP()  や \fBpselect\fP()  を使うと、プログラムで複数のファイルディスクリプターを監視し、
一つ以上のファイルディスクリプターがある種の I/O 操作の 「ready (準備ができた)」状態 (例えば、読み込み可能になった状態)
になるまで待つことができる。 ファイルディスクリプターが ready (準備ができた) とは、 (\fBread\fP(2)  などの) 対応する I/O
操作が停止 (block) なしに実行したり、 十分小さな \fBwrite\fP(2) を実行したりできる状態にあることを意味する。
.PP
\fBselect\fP()  と \fBpselect\fP()  の動作は同じであるが、以下の 3 点が異なる:
.TP 
(i)
\fBselect\fP()  では、タイムアウト時間の指定に構造体 \fIstruct timeval\fP (秒・マイクロ秒単位) を用いる。 一方、
\fBpselect\fP()  関数では、構造体 \fIstruct timespec\fP (秒・ナノ秒単位) を用いる。
.TP 
(ii)
\fBselect\fP()  は残り時間を示す \fItimeout\fP 引き数を更新することがある。 \fBpselect\fP()  はこの引き数を変更しない。
.TP 
(iii)
\fBselect\fP()  は \fIsigmask\fP 引き数を持たない。その動作は \fIsigmask\fP に NULL を指定した場合の
\fBpselect\fP()  と同じである。
.PP
3 つの独立したファイルディスクリプター集合の監視を行う。 \fIreadfds\fP に入れられたディスクリプターについては、読み込みが可能かどうかを
監視する (より正確にいうと、停止 (block) なしで読むことができるかを 調べる。ファイルの終端 (end\-of\-file) の場合も、
ファイルディスクリプターは読み込み可能として扱われる)。 \fIwritefds\fP
に入れられたディスクリプターについては、書き込み用に利用可能な領域があるかを監視する (ただし、大きな書き込みの場合には停止する可能性はある)。
\fIexceptfds\fP にあるものについては、例外の監視を行なう。システムコール終了時に、
どのファイルディスクリプターの状態が実際に変化したか示すために、 集合の内容が変更される。
ある種別のイベントを監視したいファイルディスクリプターが一つもない場合には、 対応するファイルディスクリプター集合に NULL を指定することができる。
.PP
集合を操作するために 4 つのマクロが提供されている。 \fBFD_ZERO\fP()  は集合を消去する。 \fBFD_SET\fP()  と
\fBFD_CLR\fP()  はそれぞれ指定したファイルディスクリプターの集合への追加、削除を行う。 \fBFD_ISSET\fP()
は集合にファイルディスクリプターがあるかどうか調べる; このマクロは \fBselect\fP()  が終了した後に使うと便利である。
.PP
\fInfds\fP は 3 つの集合に含まれるファイルディスクリプターの最大値に 1 を足したものである。
.PP
\fItimeout\fP 引き数は、 \fBselect\fP() がファイルディスクリプターが ready になるのを待って停止する時間を指定する。
呼び出しは以下のいずれかになるまで停止する。
.IP * 3
ファイルディスクリプターが利用可能になる。
.IP *
システムコールがシグナルハンドラーにより割り込まれた。
.IP *
タイムアウト時間が満了した。
.PP
この \fItimeout\fP 時間はシステムクロックの粒度に切り上げられ、
カーネルのスケジューリング遅延により少しだけ長くなる可能性がある点に注意すること。 \fItimeval\fP 構造体の両方のフィールドが 0 の場合、
\fBselect\fP() はすぐに復帰する (この機能はポーリング (polling) を行うのに便利である)。 \fItimeout\fP に NULL
(タイムアウトなし) が指定されると、 \fBselect\fP() は無期限に停止 (block) する。
.PP
\fIsigmask\fP は、シグナルマスク (\fBsigprocmask\fP(2)  を参照) へのポインターである。 \fIsigmask\fP が NULL
でない場合、 \fBpselect\fP()  は \fIsigmask\fP が指しているシグナルマスクで現在のシグナルマスクを置き換えてから、 "select"
関数を実行し、 終了後にシグナルマスクを元のシグナルマスクに戻す。
.PP
\fItimeout\fP 引き数の精度の違いを除くと、以下の \fBpselect\fP()  の呼び出しは、
.nf

    ready = pselect(nfds, &readfds, &writefds, &exceptfds,
                    timeout, &sigmask);

.fi
次のコールを \fIatomic\fP に実行するのと等価である。
.nf

    sigset_t origmask;

    pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
    ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
    pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.fi
.PP
\fBpselect\fP()  が必要になる理由は、シグナルやファイルディスクリプターの状態変化を 待ちたいときには、競合状態を避けるために atomic
なテストが必要になる からである。 (シグナルハンドラーが大域フラグを設定して戻る場合を考えてみよう。 この大域フラグのテストに続けて
\fBselect\fP()  を呼び出すと、 シグナルがテストの直後かつ呼び出しの直前に届いた時には \fBselect\fP()
は永久にハングしてしまうかもしれない。 一方、 \fBpselect\fP()  を使うと、まずシグナルを禁止 (block)
して、入ってくるシグナルを操作し、 望みの \fIsigmask\fP で \fBpselect\fP()  を呼び出すことで、前記の競合を避けることができる。)
.SS タイムアウト
これらの関数で使用される時間関連の構造体は、 \fI<sys/time.h>\fP で

.in +4n
.nf
struct timeval {
    long    tv_sec;         /* 秒 */
    long    tv_usec;        /* マイクロ秒 */
};
.fi
.in

や

.in +4n
.nf
struct timespec {
    long    tv_sec;         /* 秒 */
    long    tv_nsec;        /* ナノ秒 */
};
.fi
.in

のように定義されている。 (POSIX.1\-2001 での定義については下記の「注意」を参照)
.PP
秒単位以下の精度でスリープを実現する 移植性の高い方法として、 3 つの集合全てを空、 \fInfds\fP を 0 、 \fItimeout\fP を NULL
でない値に設定して \fBselect\fP()  を呼び出すという方法を使っているコードもある。
.PP
.\" .PP - it is rumored that:
.\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
.\" - it is certainly true that:
.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
Linux では、 \fBselect\fP()  は \fItimeout\fP を変更し、残りの停止時間を反映するようになっているが、
他のほとんどの実装ではこのようになっていない (POSIX.1\-2001 はどちらの動作も認めている)。 このため、 \fItimeout\fP
を参照している Linux のコードを他のオペレーティングシステムへ 移植する場合、問題が起こる。 また、ループの中で \fItimeval\fP
構造体を初期化せずにそのまま再利用して \fBselect\fP()  を複数回行なっているコードを Linux へ移植する場合にも、問題が起こる。
\fBselect\fP()  から復帰した後は \fItimeout\fP は未定義であると考えるべきである。
.SH 返り値
成功した場合、 \fBselect\fP()  と \fBpselect\fP()  は更新された 3 つのディスクリプター集合に含まれている
ファイルディスクリプターの数 (つまり、 \fIreadfds\fP, \fIwritefds\fP, \fIexceptfds\fP 中の 1
になっているビットの総数) を返す。 何も起こらずに時間切れになった場合、 ディスクリプターの数は 0 になることもある。 エラーならば \-1 を返し、
\fIerrno\fP にエラーを示す値が設定される; ファイルディスクリプター集合は変更されず、 \fItimeout\fP は不定となる。
.SH エラー
.TP 
\fBEBADF\fP
いずれかの集合に無効なファイルディスクリプターが指定された (おそらくは、すでにクローズされたファイルディスクリプターか、
エラーが発生したファイルディスクリプターが指定された)。
.TP 
\fBEINTR\fP
シグナルを受信した。
.TP 
\fBEINVAL\fP
\fInfds\fP が負、 またはリソース上限 \fBRLIMIT_NOFILE\fP (\fBgetrlimit\fP(2) 参照) より大きい。
.TP 
\fBEINVAL\fP
\fItimeout\fP に入っている値が不正である。
.TP 
\fBENOMEM\fP
内部テーブルにメモリーを割り当てることができなかった。
.SH バージョン
\fBpselect\fP()  はカーネル 2.6.16 で Linux に追加された。 それ以前は、 \fBpselect\fP()  は glibc
でエミュレートされていた (「バグ」の章を参照)。
.SH 準拠
\fBselect\fP()  は POSIX.1\-2001 と 4.4BSD (\fBselect\fP()  は 4.2BSD で最初に登場した) に準拠する。
BSD ソケット層のクローンをサポートしている非 BSD システム (System\ V 系も含む) との間でだいたい移植性がある。しかし
System\ V 系では たいがい timeout 変数を exit の前にセットするが、 BSD 系ではそうでないので注意すること。
.PP
\fBpselect\fP()  は POSIX.1g と POSIX.1\-2001 で定義されている。
.SH 注意
\fIfd_set\fP は固定サイズのバッファーである。 負や \fBFD_SETSIZE\fP 以上の値を持つ \fIfd\fP に対して \fBFD_CLR\fP()
や \fBFD_SET\fP()  を実行した場合、 どのような動作をするかは定義されていない。 また、 POSIX では \fIfd\fP
は有効なファイルディスクリプターでなければならないと規定されている。

型宣言に関しては、昔ながらの状況では \fItimeval\fP 構造体の 2 つのフィールドは (上記のように) 両方とも \fIlong\fP
型であり、構造体は \fI<sys/time.h>\fP で定義されている。 POSIX.1\-2001 の下では、以下のようになっている。

.in +4n
.nf
struct timeval {
         time_t         tv_sec;     /* 秒 */
         suseconds_t    tv_usec;    /* マイクロ秒 */
};
.fi
.in

この構造体は \fI<sys/select.h>\fP で定義されており、データ型 \fItime_t\fP と \fIsuseconds_t\fP は
\fI<sys/types.h>\fP で定義されている。
.LP
プロトタイプに関しては、昔ながらの状況で \fBselect\fP()  を使いたい場合は、 \fI<time.h>\fP
をインクルードすればよい。 POSIX.1\-2001 の環境で \fBselect\fP()  と \fBpselect\fP()  を使いたい場合は、
\fI<sys/select.h>\fP をインクルードすればよい。

glibc 2.0 では \fI<sys/select.h>\fP が提供する \fBpselect\fP()  のプロトタイプが間違っている。
glibc 2.1 から 2.2.1 では \fB_GNU_SOURCE\fP が定義されている場合に、 \fBpselect\fP()  が提供される。
glibc 2.2.2 以降では、 \fBpselect\fP()  を使用するには、「書式」に記載された要件を満たす必要がある。
.SS マルチスレッドアプリケーション
.\"
\fBselect\fP() で監視中のファイルディスクリプターが別のスレッドでクローズされた場合、どのような結果になるかは規定されていない。いくつかの
UNIX システムでは、 \fBselect\fP() は停止 (block) せず、すぐ返り、ファイルディスクリプターが ready だと報告される
(\fBselect\fP() が返ってから I/O 操作が実行されるまでの間に、 別のファイルディスクリプターが再度オープンされない限り、 それ以降の
I/O 操作はおそらく失敗するだろう)。 Linux (や他のいくつかのシステム) では、 別のスレッドでファイルディスクリプターがクローズされても
\fBselect\fP() には影響を与えない。
まとめると、このような場合に特定の動作に依存しているアプリケーションは「バグっている」と考えなければならない。
.SS "C ライブラリとカーネル ABI の違い"
このページで説明している \fBpselect\fP() のインターフェースは、glibc に
実装されているものである。内部で呼び出される Linux のシステムコールは
\fBpselect6\fP() という名前である。このシステムコールは glibc のラッパー
関数とは少し違った動作をする。

Linux の \fBpselect6\fP() システムコールは \fItimeout\fP 引き数を変更する。
しかし、glibc のラッパー関数は、システムコールに渡す timeout 引き数と
してローカル変数を使うことでこの動作を隠蔽している。このため、glibc の
\fBpselect\fP() 関数は \fItimeout\fP 引き数を変更しない。
これが POSIX.1\-2001 が要求している動作である。

\fBpselect6\fP() システムコールの最後の引き数は \fIsigset_t\ *\fP 型の
ポインターではなく、以下に示す構造体である。
.in +4
.nf

struct {
    const sigset_t *ss;     /* シグナル集合へのポインター */
    size_t          ss_len; /* 'ss' が指すオブジェクトのサイズ
                               (バイト数) */
};

.fi
.in
このようにすることで、ほとんどのアーキテクチャーがサポートしている
システムコールの引き数が最大で 6 個という事実を満たしつつ、
\fBpselect6\fP() システムコールがシグナル集合へのポインターとシグナル集合
のサイズの両方を取得することができるのである。
.SH バグ
glibc 2.0 では、 \fIsigmask\fP 引き数を取らないバージョンの \fBpselect\fP()  が提供されていた。

バージョン 2.1 以降の glibc では、 \fBpselect\fP()  は \fBsigprocmask\fP(2)  と \fBselect\fP()
を使ってエミュレートされていた。 この実装にはきわどい競合条件において脆弱性が残っていた。 この競合条件における問題を防止するために
\fBpselect\fP()  は設計されたのである。 最近のバージョンの glibc では、カーネルがサポートしている場合には、 (競合が起こらない)
\fBpselect\fP()  システムコールが使用される。

\fBpselect\fP() がないシステムにおいて、シグナルの捕捉を信頼性があり (移植
性も高い) 方法で行うには、 自己パイプ (self\-pipe) という技を使うとよい。
この方法では、シグナルハンドラーはパイプへ 1 バイトのデータを書き込み、
同じパイプのもう一端をメインプログラムの \fBselect\fP() で監視する (一杯に
なったパイプへの書き込みや空のパイプから読み出しを行った際に起こるであ
ろう停止 (blocking) を避けるためには、パイプへの読み書きの際には 非停止
(nonblocking) I/O を使用するとよい)。

.\" Stevens discusses a case where accept can block after select
.\" returns successfully because of an intervening RST from the client.
.\" Maybe the kernel should have returned EIO in such a situation?
Linux では、 \fBselect\fP()  がソケットファイルディスクリプターで "読み込みの準備ができた" と報告した場合でも、 この後で read
を行うと停止 (block) することがある。このような状況は、 例えば、データが到着したが、検査でチェックサム異常が見つかり廃棄された時
などに起こりえる。他にもファイルディスクリプターが準備できたと間違って 報告される状況が起こるかもしれない。
したがって、停止すべきではないソケットに対しては \fBO_NONBLOCK\fP を使うとより安全であろう。

Linux では、 \fBselect\fP()  がシグナルハンドラーにより割り込まれた場合 (つまり \fBEINTR\fP エラーが返る場合)、
\fItimeout\fP も変更する。 これは POSIX.1\-2001 では認められていない挙動である。 Linux の \fBpselect\fP()
システムコールも同じ挙動をするが、 glibc のラッパー関数がこの挙動を隠蔽している。 具体的には、glibc のラッパー関数の内部で、
\fItimeout\fP をローカル変数にコピーし、 このローカル変数をシステムコールに渡している。
.SH 例
.nf
#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>

int
main(void)
{
    fd_set rfds;
    struct timeval tv;
    int retval;

    /* stdin (fd 0) を監視し、入力があった場合に表示する。*/
    FD_ZERO(&rfds);
    FD_SET(0, &rfds);

    /* 5 秒間監視する。*/
    tv.tv_sec = 5;
    tv.tv_usec = 0;

    retval = select(1, &rfds, NULL, NULL, &tv);
    /* この時点での tv の値を信頼してはならない。*/

    if (retval == \-1)
        perror("select()");
    else if (retval)
        printf("今、データが取得できました。\en");
        /* FD_ISSET(0, &rfds) が true になる。*/
    else
        printf("5 秒以内にデータが入力されませんでした。\en");

    exit(EXIT_SUCCESS);
}
.fi
.SH 関連項目
\fBaccept\fP(2), \fBconnect\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBrecv\fP(2),
\fBrestart_syscall\fP(2), \fBsend\fP(2), \fBsigprocmask\fP(2), \fBwrite\fP(2),
\fBepoll\fP(7), \fBtime\fP(7)

考察と使用例の書かれたチュートリアルとして、 \fBselect_tut\fP(2)  がある。
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。