.\"	%NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp %
.\" %FreeBSD: src/lib/libc/sys/poll.2,v 1.15 2004/07/02 23:52:13 ru Exp %
.\"
.\" Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Charles M. Hannum.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.Dd July 8, 2002
.Dt POLL 2
.Os
.Sh 名称
.Nm poll
.Nd 同期的な入出力の多重化
.Sh ライブラリ
.Lb libc
.Sh 書式
.In poll.h
.Ft int
.Fn poll "struct pollfd fds[]" "nfds_t nfds" "int timeout"
.Sh 解説
.Fn poll
システムコールはファイル記述子の集合を調査して、
それらのいずれかで入出力の準備ができているか否かを調べます。
.Fa fds
引数は
.In poll.h
で定義された pollfd 配列を指すポインタ (後述) です。
.Fa nfds
引数は
.Fa fds
配列のサイズを決定します。
.Bd -literal
struct pollfd {
    int    fd;       /* ファイル記述子 */
    short  events;   /* 検索するイベント */
    short  revents;  /* 返されたイベント */
};
.Ed
.Pp
.Fa struct pollfd
のフィールドは次のとおりです:
.Bl -tag -width XXXrevents
.It fd
調査するファイル記述子。
もし fd が -1 なら
.Fa revents
はクリアされ (0 に設定)、pollfd はチェックされません。
.It events
調査するイベント (後述)。
.It revents
発生したイベント (後述)。
.El
.Pp
.Fa events
と
.Fa revents
内のビットマスクには次のビットがあります:
.Bl -tag -width XXXPOLLWRNORM
.It POLLIN
高優先データ以外のデータはブロックせずに読取りできます。
.It POLLRDNORM
通常データはブロックせずに読取りできます。
.It POLLRDBAND
優先順位が 0 でないデータはブロックせずに読取りできます。
.It POLLPRI
高優先データはブロックせずに読取りできます。
.It POLLOUT
.It POLLWRNORM
通常データはブロックせずに書き込めます。
.It POLLWRBAND
優先順位が 0 でないデータはブロックせずに書き込めます。
.It POLLERR
デバイスまたはソケット上に例外状態が起きました。
このフラグは、
.Fa events
ビットマスクに存在していなくても必ずチェックされます。
.It POLLHUP
デバイスまたはソケットが切断されています。
このフラグは、
.Fa events
ビットマスク内に存在しなくても必ずチェックされます。
POLLHUP
と
POLLOUT
は、
.Fa revents
ビットマスク内に同時に存在することが決してないことに注意してください。
.It POLLNVAL
ファイル記述子がオープンされていません。
このフラグは、
.Fa events
ビットマスク内に存在しなくても必ずチェックされます。
.El
.Pp
.Fa timeout
が 0 でも INFTIM (-1) でもない場合、この値はいずれかのファイル記述子が
準備完了になるのを待機する最大間隔 (ミリ秒単位) です。
.Fa timeout
が INFTIM (-1) の場合、
.Fn poll
は無期限にブロックします。
.Fa timeout
が 0 の場合
.Fn poll
はブロックせずに戻ります。
.Sh 戻り値
.Fn poll
システムコールは入出力の準備が完了した記述子の番号を返します。
エラーが起きた場合は -1 を返します。
時間切れになると
.Fn poll
は 0 を返します。
システムコールが割り込まれたことによるエラーも含めて
.Fn poll
がエラーで戻った場合、
.Fa fds
配列は変更されません。
.Sh 互換性
この実装は、ファイル記述子によって
.Fn poll
がエラーにならないという点で、過去のものと異なっています。
過去の実装においてエラーになるであろう場合 (たとえば
.Xr revoke 2
された記述子を検査しようとした場合)、この実装は代わりに
.Fa events
ビットマスクを
.Fa revents
ビットマスクにコピーします。
この記述子上で入出力を実行しようとするとエラーが返されます。
この動作はより便利であると考えられています。
.Sh エラー
.Fn poll
は次のエラーで戻ります:
.Bl -tag -width Er
.It Bq Er EFAULT
.Fa fds
引数は、プロセスに割り当てられたアドレス空間の範囲外を指しています。
.It Bq Er EINTR
時間切れになる前に、そして選択されたイベントが発生する前に
シグナルを受信しました。
.It Bq Er EINVAL
時間制限として負の値が指定されました。
.El
.Sh 関連項目
.Xr accept 2 ,
.Xr connect 2 ,
.Xr kqueue 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr send 2 ,
.Xr write 2
.Sh バグ
.Fa events
ビットマスクと
.Fa revents
ビットマスクのいくつかのフィールド間の違いは、
STREAMS 以外では実用的ではありません。
それらのフィールドは、既存のソフトウェアとの互換性を
保つために定義されています。
.Sh 歴史
.Fn poll
関数は
.At V
で登場しました。
このマニュアルページと実装の主要な部分は
.Nx
から得たものです。