]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" |
2 | .\" epoll by Davide Libenzi ( efficient event notification retrieval ) | |
3 | .\" Copyright (C) 2003 Davide Libenzi | |
4 | .\" | |
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 License | |
16 | .\" along with this program; if not, write to the Free Software | |
17 | .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
18 | .\" | |
19 | .\" Davide Libenzi <davidel@xmailserver.org> | |
20 | .\" | |
21 | .\" | |
c13182ef | 22 | .\" FIXME 2.6.19-rc5 has epoll_pwait(); this should be documented |
e0614973 MK |
23 | .\" on this page. |
24 | .\" | |
fea681da MK |
25 | .TH EPOLL_WAIT 2 "23 October 2002" Linux "Linux Programmer's Manual" |
26 | .SH NAME | |
27 | epoll_wait \- wait for an I/O event on an epoll file descriptor | |
28 | .SH SYNOPSIS | |
616c0fd3 | 29 | .nf |
fea681da MK |
30 | .B #include <sys/epoll.h> |
31 | .sp | |
c13182ef | 32 | .BI "int epoll_wait(int " epfd ", struct epoll_event *" events , |
616c0fd3 MK |
33 | .BI " int " maxevents ", int " timeout); |
34 | .fi | |
fea681da MK |
35 | .SH DESCRIPTION |
36 | Wait for events on the | |
37 | .B epoll | |
38 | file descriptor | |
39 | .I epfd | |
40 | for a maximum time of | |
41 | .I timeout | |
c13182ef MK |
42 | milliseconds. |
43 | The memory area pointed to by | |
fea681da MK |
44 | .I events |
45 | will contain the events that will be available for the caller. | |
46 | Up to | |
47 | .I maxevents | |
48 | are returned by | |
49 | .BR epoll_wait (2). | |
50 | The | |
51 | .I maxevents | |
c13182ef MK |
52 | parameter must be greater than zero. |
53 | Specifying a | |
fea681da MK |
54 | .I timeout |
55 | of \-1 makes | |
56 | .BR epoll_wait (2) | |
57 | wait indefinitely, while specifying a | |
58 | .I timeout | |
59 | equal to zero makes | |
60 | .BR epoll_wait (2) | |
c13182ef | 61 | to return immediately even if no events are available |
6e126ed6 | 62 | (return code equal to zero). |
fea681da | 63 | The |
8478ee02 | 64 | .I struct epoll_event |
fea681da MK |
65 | is defined as : |
66 | .sp | |
cf0a9ace | 67 | .in +0.5i |
fea681da | 68 | .nf |
cf0a9ace MK |
69 | typedef union epoll_data { |
70 | void *ptr; | |
71 | int fd; | |
72 | __uint32_t u32; | |
73 | __uint64_t u64; | |
74 | } epoll_data_t; | |
fea681da | 75 | |
cf0a9ace MK |
76 | struct epoll_event { |
77 | __uint32_t events; /* Epoll events */ | |
78 | epoll_data_t data; /* User data variable */ | |
79 | }; | |
fea681da | 80 | .fi |
cf0a9ace | 81 | .in -0.5i |
fea681da MK |
82 | |
83 | The | |
84 | .I data | |
85 | of each returned structure will contain the same data the user set with a | |
86 | .BR epoll_ctl (2) | |
87 | .IR ( EPOLL_CTL_ADD , EPOLL_CTL_MOD ) | |
88 | while the | |
89 | .I events | |
90 | member will contain the returned event bit field. | |
91 | .SH "RETURN VALUE" | |
c13182ef | 92 | When successful, |
fea681da MK |
93 | .BR epoll_wait (2) |
94 | returns the number of file descriptors ready for the requested I/O, or zero | |
95 | if no file descriptor became ready during the requested | |
96 | .I timeout | |
c13182ef MK |
97 | milliseconds. |
98 | When an error occurs, | |
fea681da MK |
99 | .BR epoll_wait (2) |
100 | returns \-1 and | |
101 | .I errno | |
102 | is set appropriately. | |
103 | .SH ERRORS | |
104 | .TP | |
105 | .B EBADF | |
106 | .I epfd | |
107 | is not a valid file descriptor. | |
108 | .TP | |
109 | .B EFAULT | |
110 | The memory area pointed to by | |
111 | .I events | |
112 | is not accessible with write permissions. | |
113 | .TP | |
c5a2d222 MK |
114 | .B EINTR |
115 | The call was interrupted by a signal handler before any of the | |
116 | requested events occurred or the | |
117 | .I timeout | |
118 | expired. | |
119 | .TP | |
fea681da | 120 | .B EINVAL |
c13182ef | 121 | .IR epfd |
fea681da MK |
122 | is not an |
123 | .B epoll | |
3d9a2200 | 124 | file descriptor, or |
fea681da | 125 | .I maxevents |
3d9a2200 | 126 | is less than or equal to zero. |
fea681da MK |
127 | .SH CONFORMING TO |
128 | .BR epoll_wait (2) | |
75b48e9d MK |
129 | is Linux specific, and was introduced in kernel 2.5.44. |
130 | .\" The interface should be finalized by Linux kernel 2.5.66. | |
fea681da MK |
131 | .SH "SEE ALSO" |
132 | .BR epoll_create (2), | |
133 | .BR epoll_ctl (2), | |
2315114c | 134 | .BR epoll (7) |