release/man2/epoll_wait.2

   1 .\"  Copyright (C) 2003  Davide Libenzi
   2 .\"  Davide Libenzi <davidel@xmailserver.org>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   5 .\"  This program is free software; you can redistribute it and/or modify
   6 .\"  it under the terms of the GNU General Public License as published by
   7 .\"  the Free Software Foundation; either version 2 of the License, or
   8 .\"  (at your option) any later version.
   9 .\"
  10 .\"  This program is distributed in the hope that it will be useful,
  11 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"  GNU General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public
  16 .\" License along with this manual; if not, see
  17 .\" <http://www.gnu.org/licenses/>.
  18 .\" %%%LICENSE_END
  19 .\"
  20 .\" 2007-04-30: mtk, Added description of epoll_pwait()
  21 .\"
  22 .\"*******************************************************************
  23 .\"
  24 .\" This file was generated with po4a. Translate the source file.
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
  29 .\"         all rights reserved.
  30 .\" Translated Wed Jun 16 03:05:40 JST 2004
  31 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  32 .\" Updated & Modified Tue Apr 19 07:05:42 JST 2005 by Yuichi SATO
  33 .\" Updated 2007-06-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.51
  34 .\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.18
  35 .\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
  36 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  37 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  38 .\"
  39 .TH EPOLL_WAIT 2 2014\-01\-31 Linux "Linux Programmer's Manual"
  40 .SH 名前
  41 epoll_wait, epoll_pwait \- epoll ファイルディスクリプタの I/O イベントを待つ
  42 .SH 書式
  43 .nf
  44 \fB#include <sys/epoll.h>\fP
  45 .sp
  46 \fBint epoll_wait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
  47 \fB               int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB);\fP
  48 \fBint epoll_pwait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
  49 \fB               int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB,\fP
  50 \fB               const sigset_t *\fP\fIsigmask\fP\fB);\fP
  51 .fi
  52 .SH 説明
  53 \fBepoll_wait\fP() システムコールは、ファイルディスクリプタ \fIepfd\fP で参照される
  54 \fBepoll\fP(7) インスタンスに対するイベントを待つ。 \fIevents\fP が指すメモリ領域には、
  55 呼び出し側が利用可能なイベントが格納される。最大 \fImaxevents\fP 個のイベントが
  56 \fBepoll_wait\fP() によって返される。
  57 \fImaxevents\fP 引き数は 0 より大きくなければならない。
  58
  59 \fItimeout\fP 引き数は \fBepoll_wait\fP() が停止する時間をミリ秒で指定する。 \fBepoll_wait\fP()
  60 の呼び出しは以下のいずれかになるまで停止する。
  61 .IP * 3
  62 ファイルディスクリプタがイベントを配送した
  63 .IP *
  64 呼び出しがシグナルハンドラーにより割り込まれた
  65 .IP *
  66 タイムアウトが満了する
  67 .PP
  68 \fItimeout\fP 時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少しだけ長くなる可能性がある点に注意すること。
  69 \fItimeout\fP を \-1 に指定すると、 \fBepoll_wait\fP() は無限に停止する。 \fItimeout\fP を 0 に指定すると、
  70 \fBepoll_wait\fP() は利用可能なイベントがなくても、すぐに返る。
  71
  72 \fIstruct epoll_event\fP は以下のように定義される:
  73 .sp
  74 .in +4n
  75 .nf
  76 typedef union epoll_data {
  77     void    *ptr;
  78     int      fd;
  79     uint32_t u32;
  80     uint64_t u64;
  81 } epoll_data_t;
  82
  83 struct epoll_event {
  84     uint32_t     events;    /* epoll イベント */
  85     epoll_data_t data;      /* ユーザデータ変数 */
  86 };
  87 .fi
  88 .in
  89
  90 返される構造体の \fIdata\fP メンバには、ユーザが \fBepoll_ctl\fP(2)  (\fBEPOLL_CTL_ADD\fP,
  91 \fBEPOLL_CTL_MOD\fP)  で指定したデータが格納される。 一方、 \fIevents\fP
  92 メンバには返された利用可能なイベントのビットフィールドが格納される。
  93 .SS epoll_pwait()
  94 \fBepoll_wait\fP()  と \fBepoll_pwait\fP()  の関係は、 \fBselect\fP(2)  と \fBpselect\fP(2)
  95 の関係と同様である。 \fBpselect\fP(2)  同様、 \fBepoll_pwait\fP()
  96 を使うと、アプリケーションは、ファイルディスクリプタが準備できた状態になるか、 シグナルが捕捉されるまで、安全に待つことができる。
  97
  98 以下の \fBepoll_pwait\fP()  の呼び出しは、
  99 .nf
 100
 101     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 102
 103 .fi
 104 次の呼び出しを \fIatomic\fP に実行するのと等価である。
 105 .nf
 106
 107     sigset_t origmask;
 108
 109     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 110     ready = epoll_wait(epfd, &events, maxevents, timeout);
 111     sigprocmask(SIG_SETMASK, &origmask, NULL);
 112 .fi
 113 .PP
 114 \fIsigmask\fP 引き数には NULL を指定してもよい。 その場合には、 \fBepoll_pwait\fP()  は \fBepoll_wait\fP()
 115 と等価となる。
 116 .SH 返り値
 117 成功した場合、 \fBepoll_wait\fP()  は要求された I/O に対して準備ができているファイルディスクリプタの数を返す。 また要求された
 118 \fItimeout\fP ミリ秒の間にファイルディスクリプタが準備できない場合は、0 を返す。 エラーが起こった場合、 \fBepoll_wait\fP()  は
 119 \-1 を返し、 \fIerrno\fP を適切に設定する。
 120 .SH エラー
 121 .TP
 122 \fBEBADF\fP
 123 \fIepfd\fP が有効なファイルディスクリプタでない。
 124 .TP
 125 \fBEFAULT\fP
 126 \fIevents\fP で指されるメモリ領域に書き込み権限でアクセスできない。
 127 .TP
 128 \fBEINTR\fP
 129 (1) 要求されたどのイベントも発生せず、かつ (2) \fItimeout\fP の期限が切れる前に、システムコールがシグナルハンドラによって割り込まれた。
 130 \fBsignal\fP(7) 参照。
 131 .TP
 132 \fBEINVAL\fP
 133 \fIepfd\fP が \fBepoll\fP ファイルディスクリプタでない。 または \fImaxevents\fP が 0 以下である。
 134 .SH バージョン
 135 .\" To be precise: kernel 2.5.44.
 136 .\" The interface should be finalized by Linux kernel 2.5.66.
 137 \fBepoll_wait\fP() はカーネル 2.6 で追加された。
 138 ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。
 139
 140 \fBepoll_pwait\fP() はカーネル 2.6.19 で Linux に追加された。
 141 ライブラリによるサポートは glibc バージョン 2.6 以降で提供されている。
 142 .SH 準拠
 143 \fBepoll_wait\fP() は Linux 独自である。
 144 .SH 注意
 145 あるスレッドが \fBepoll_pwait\fP() を呼び出して停止されている間に、
 146 別のスレッドが wait 中の \fBepoll\fP インストールにファイルディスクリプタを
 147 追加することがある。新しいファイルディスクリプタでイベントが発生すると、
 148 \fBepoll_wait\fP() の呼び出しによる停止が解除されることになる。
 149
 150 \fBepoll_wait\fP() で監視中の \fBepoll\fP
 151 インスタンス内のファイルディスクリプタが別のスレッドによってクローズされた場合に何が起こるかの議論については、 \fBselect\fP(2)
 152 を参照してほしい。
 153 .SH バグ
 154 バージョン 2.6.37 より前のカーネルでは、おおよそ \fILONG_MAX / HZ\fP ミリ秒より大きい \fItimeout\fP 値は \-1
 155 (つまり無限大) として扱われる。したがって、例えば、\fIsizeof(long)\fP が 4 で、カーネルの \fIHZ\fP の値が 1000
 156 のシステムでは、 35.79 分よりも大きなタイムアウトは無限大として扱われるということである。
 157 .SH 関連項目
 158 \fBepoll_create\fP(2), \fBepoll_ctl\fP(2), \fBepoll\fP(7)
 159 .SH この文書について
 160 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.67 の一部
 161 である。プロジェクトの説明とバグ報告に関する情報は
 162 http://www.kernel.org/doc/man\-pages/ に書かれている。