1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
.\" Copyright (C) 2003 Davide Libenzi
.\" Davide Libenzi <davidel@xmailserver.org>
.\" and Copyright 2007, 2012, 2014, 2018 Michael Kerrisk <tk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
.\" 2007-04-30: mtk, Added description of epoll_pwait()
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
.\" all rights reserved.
.\" Translated Wed Jun 16 03:05:40 JST 2004
.\" by Yuichi SATO <ysato444@yahoo.co.jp>
.\" Updated & Modified Tue Apr 19 07:05:42 JST 2005 by Yuichi SATO
.\" Updated 2007-06-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.51
.\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.18
.\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH EPOLL_WAIT 2 2020\-04\-11 Linux "Linux Programmer's Manual"
.SH 名前
epoll_wait, epoll_pwait \- epoll ファイルディスクリプターの I/O イベントを待つ
.SH 書式
.nf
\fB#include <sys/epoll.h>\fP
.PP
\fBint epoll_wait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
\fB int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB);\fP
\fBint epoll_pwait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
\fB int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB,\fP
\fB const sigset_t *\fP\fIsigmask\fP\fB);\fP
.fi
.SH 説明
The \fBepoll_wait\fP() system call waits for events on the \fBepoll\fP(7)
instance referred to by the file descriptor \fIepfd\fP. The buffer pointed to
by \fIevents\fP is used to return information from the ready list about file
descriptors in the interest list that have some events available. Up to
\fImaxevents\fP are returned by \fBepoll_wait\fP(). The \fImaxevents\fP argument
must be greater than zero.
.PP
The \fItimeout\fP argument specifies the number of milliseconds that
\fBepoll_wait\fP() will block. Time is measured against the
\fBCLOCK_MONOTONIC\fP clock.
.PP
A call to \fBepoll_wait\fP() will block until either:
.IP \(bu 2
ファイルディスクリプターがイベントを配送した
.IP \(bu
呼び出しがシグナルハンドラーにより割り込まれた
.IP \(bu
タイムアウトが満了する
.PP
\fItimeout\fP 時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少しだけ長くなる可能性がある点に注意すること。
\fItimeout\fP を \-1 に指定すると、 \fBepoll_wait\fP() は無限に停止する。 \fItimeout\fP を 0 に指定すると、
\fBepoll_wait\fP() は利用可能なイベントがなくても、すぐに返る。
.PP
\fIstruct epoll_event\fP は以下のように定義される。
.PP
.in +4n
.EX
typedef union epoll_data {
void *ptr;
int fd;
uint32_t u32;
uint64_t u64;
} epoll_data_t;
struct epoll_event {
uint32_t events; /* epoll イベント */
epoll_data_t data; /* ユーザーデータ変数 */
};
.EE
.in
.PP
The \fIdata\fP field of each returned \fIepoll_event\fP structure contains the
same data as was specified in the most recent call to \fBepoll_ctl\fP(2)
(\fBEPOLL_CTL_ADD\fP, \fBEPOLL_CTL_MOD\fP) for the corresponding open file
descriptor.
.PP
.\"
The \fIevents\fP field is a bit mask that indicates the events that have
occurred for the corresponding open file description. See \fBepoll_ctl\fP(2)
for a list of the bits that may appear in this mask.
.SS epoll_pwait()
\fBepoll_wait\fP() と \fBepoll_pwait\fP() の関係は、 \fBselect\fP(2) と \fBpselect\fP(2)
の関係と同様である。 \fBpselect\fP(2) 同様、 \fBepoll_pwait\fP()
を使うと、アプリケーションは、ファイルディスクリプターが準備できた状態になるか、 シグナルが捕捉されるまで、安全に待つことができる。
.PP
以下の \fBepoll_pwait\fP() の呼び出しは、
.PP
.in +4n
.EX
ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
.EE
.in
.PP
次の呼び出しを \fIatomic\fP に実行するのと等価である。
.PP
.in +4n
.EX
sigset_t origmask;
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ready = epoll_wait(epfd, &events, maxevents, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
.PP
\fIsigmask\fP 引数には NULL を指定してもよい。 その場合には、 \fBepoll_pwait\fP() は \fBepoll_wait\fP()
と等価となる。
.SH 返り値
成功した場合、 \fBepoll_wait\fP() は要求された I/O に対して準備ができているファイルディスクリプターの数を返す。 また要求された
\fItimeout\fP ミリ秒の間にファイルディスクリプターが準備できない場合は、0 を返す。 エラーが起こった場合、 \fBepoll_wait\fP()
は \-1 を返し、 \fIerrno\fP を適切に設定する。
.SH エラー
.TP
\fBEBADF\fP
\fIepfd\fP が有効なファイルディスクリプターでない。
.TP
\fBEFAULT\fP
\fIevents\fP で指されるメモリー領域に書き込み権限でアクセスできない。
.TP
\fBEINTR\fP
(1) 要求されたどのイベントも発生せず、かつ (2) \fItimeout\fP
の期限が切れる前に、システムコールがシグナルハンドラーによって割り込まれた。 \fBsignal\fP(7) 参照。
.TP
\fBEINVAL\fP
\fIepfd\fP が \fBepoll\fP ファイルディスクリプターでない。 または \fImaxevents\fP が 0 以下である。
.SH バージョン
.\" To be precise: kernel 2.5.44.
.\" The interface should be finalized by Linux kernel 2.5.66.
\fBepoll_wait\fP() はカーネル 2.6 で追加された。
ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。
.PP
\fBepoll_pwait\fP() はカーネル 2.6.19 で Linux に追加された。
ライブラリによるサポートは glibc バージョン 2.6 以降で提供されている。
.SH 準拠
\fBepoll_wait\fP() は Linux 独自である。
.SH 注意
あるスレッドが \fBepoll_wait\fP() を呼び出して停止されている間に、別のスレッドが wait 中の \fBepoll\fP
インストールにファイルディスクリプターを追加することがある。新しいファイルディスクリプターでイベントが発生すると、 \fBepoll_wait\fP()
の呼び出しによる停止が解除されることになる。
.PP
If more than \fImaxevents\fP file descriptors are ready when \fBepoll_wait\fP()
is called, then successive \fBepoll_wait\fP() calls will round robin through
the set of ready file descriptors. This behavior helps avoid starvation
scenarios, where a process fails to notice that additional file descriptors
are ready because it focuses on a set of file descriptors that are already
known to be ready.
.PP
Note that it is possible to call \fBepoll_wait\fP() on an \fBepoll\fP instance
whose interest list is currently empty (or whose interest list becomes empty
because file descriptors are closed or removed from the interest in another
thread). The call will block until some file descriptor is later added to
the interest list (in another thread) and that file descriptor becomes
ready.
.SH バグ
バージョン 2.6.37 より前のカーネルでは、おおよそ \fILONG_MAX / HZ\fP ミリ秒より大きい \fItimeout\fP 値は \-1
(つまり無限大) として扱われる。したがって、例えば、\fIsizeof(long)\fP が 4 で、カーネルの \fIHZ\fP の値が 1000
のシステムでは、 35.79 分よりも大きなタイムアウトは無限大として扱われるということである。
.SS "C ライブラリとカーネルの違い"
素の \fBepoll_pwait\fP() システムコールは 6 番目の引数 \fIsize_t sigsetsize\fP を取る。 この引数は
\fIsigmask\fP 引数のバイト単位のサイズを指定する。 glibc の \fBepoll_pwait\fP() ラッパー関数は、この引数に固定値
(\fIsizeof(sigset_t)\fP と同じ) を指定する。
.SH 関連項目
\fBepoll_create\fP(2), \fBepoll_ctl\fP(2), \fBepoll\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。
|
