]>
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 | .\" | |
22 | .TH EPOLL_CTL 2 "2002-10-23" Linux "Linux Programmer's Manual" | |
23 | .SH NAME | |
24 | epoll_ctl \- control interface for an epoll descriptor | |
25 | .SH SYNOPSIS | |
26 | .B #include <sys/epoll.h> | |
27 | .sp | |
6e126ed6 | 28 | .BI "int epoll_ctl(int " epfd ", int " op ", int " fd ", struct epoll_event *" event ) |
fea681da MK |
29 | .SH DESCRIPTION |
30 | Control an | |
31 | .B epoll | |
32 | descriptor, | |
33 | .IR epfd , | |
019934ed | 34 | by requesting that the operation |
fea681da MK |
35 | .IR op |
36 | be performed on the target file descriptor, | |
37 | .IR fd . | |
38 | The | |
39 | .IR event | |
40 | describes the object linked to the file descriptor | |
41 | .IR fd . | |
42 | The | |
8478ee02 | 43 | .I struct epoll_event |
fea681da MK |
44 | is defined as : |
45 | .sp | |
46 | .nf | |
fea681da MK |
47 | typedef union epoll_data { |
48 | void *ptr; | |
49 | int fd; | |
50 | __uint32_t u32; | |
51 | __uint64_t u64; | |
52 | } epoll_data_t; | |
53 | ||
54 | struct epoll_event { | |
55 | __uint32_t events; /* Epoll events */ | |
56 | epoll_data_t data; /* User data variable */ | |
57 | }; | |
fea681da MK |
58 | .fi |
59 | ||
60 | The | |
61 | .I events | |
62 | member is a bit set composed using the following available event | |
63 | types : | |
64 | .TP | |
65 | .B EPOLLIN | |
66 | The associated file is available for | |
67 | .BR read (2) | |
68 | operations. | |
69 | .TP | |
70 | .B EPOLLOUT | |
71 | The associated file is available for | |
72 | .BR write (2) | |
73 | operations. | |
74 | .TP | |
75 | .B EPOLLPRI | |
76 | There is urgent data available for | |
77 | .BR read (2) | |
78 | operations. | |
79 | .TP | |
80 | .B EPOLLERR | |
81 | Error condition happened on the associated file descriptor. | |
3d9a2200 MK |
82 | .BR epoll_wait (2) |
83 | will always wait for this event; it is not necessary to set it in | |
84 | .IR events . | |
fea681da MK |
85 | .TP |
86 | .B EPOLLHUP | |
87 | Hang up happened on the associated file descriptor. | |
3d9a2200 MK |
88 | .BR epoll_wait (2) |
89 | will always wait for this event; it is not necessary to set it in | |
90 | .IR events . | |
fea681da MK |
91 | .TP |
92 | .B EPOLLET | |
93 | Sets the Edge Triggered behaviour for the associated file descriptor. | |
94 | The default behaviour for | |
95 | .B epoll | |
96 | is Level Triggered. See | |
97 | .BR epoll (4) | |
704a18f0 | 98 | for more detailed information about Edge and Level Triggered event |
fea681da MK |
99 | distribution architectures. |
100 | .TP | |
fee44d9b | 101 | .BR EPOLLONESHOT " (since kernel 2.6.2)" |
019934ed MK |
102 | Sets the one-shot behaviour for the associated file descriptor. |
103 | This means that after an event is pulled out with | |
fea681da MK |
104 | .BR epoll_wait (2) |
105 | the associated file descriptor is internally disabled and no other events | |
106 | will be reported by the | |
107 | .B epoll | |
108 | interface. The user must call | |
109 | .BR epoll_ctl (2) | |
110 | with | |
111 | .B EPOLL_CTL_MOD | |
112 | to re-enable the file descriptor with a new event mask. | |
113 | .PP | |
fea681da MK |
114 | The |
115 | .B epoll | |
116 | interface supports all file descriptors that support | |
117 | .BR poll (2). | |
118 | Valid values for the | |
119 | .IR op | |
120 | parameter are : | |
121 | .RS | |
122 | .TP | |
123 | .B EPOLL_CTL_ADD | |
124 | Add the target file descriptor | |
125 | .I fd | |
126 | to the | |
127 | .B epoll | |
128 | descriptor | |
129 | .I epfd | |
130 | and associate the event | |
131 | .I event | |
132 | with the internal file linked to | |
133 | .IR fd . | |
134 | .TP | |
135 | .B EPOLL_CTL_MOD | |
136 | Change the event | |
137 | .I event | |
99d2b7a2 | 138 | associated with the target file descriptor |
fea681da MK |
139 | .IR fd . |
140 | .TP | |
141 | .B EPOLL_CTL_DEL | |
142 | Remove the target file descriptor | |
143 | .I fd | |
144 | from the | |
145 | .B epoll | |
146 | file descriptor, | |
147 | .IR epfd . | |
e8de013a MK |
148 | The |
149 | .IR event | |
019934ed | 150 | is ignored and can be NULL (but see BUGS below). |
fea681da MK |
151 | .RE |
152 | .SH "RETURN VALUE" | |
153 | When successful, | |
154 | .BR epoll_ctl (2) | |
155 | returns zero. When an error occurs, | |
156 | .BR epoll_ctl (2) | |
157 | returns \-1 and | |
158 | .I errno | |
159 | is set appropriately. | |
160 | .SH ERRORS | |
161 | .TP | |
162 | .B EBADF | |
fea681da | 163 | .I epfd |
3d9a2200 MK |
164 | is not a valid file descriptor. |
165 | .TP | |
166 | .B EEXIST | |
167 | .I op | |
168 | was EPOLL_CTL_ADD, and the supplied file descriptor | |
169 | .IR fd | |
170 | is already in | |
171 | .IR epfd . | |
fea681da MK |
172 | .TP |
173 | .B EINVAL | |
3d9a2200 | 174 | .IR epfd |
fea681da MK |
175 | is not an |
176 | .B epoll | |
3d9a2200 MK |
177 | file descriptor, |
178 | or | |
179 | .IR fd | |
180 | is the same as | |
181 | .IR epfd , | |
182 | or the requested operation | |
fea681da MK |
183 | .I op |
184 | is not supported by this interface. | |
185 | .TP | |
3d9a2200 MK |
186 | .B ENOENT |
187 | .I op | |
188 | was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and | |
189 | .IR fd | |
190 | is not in | |
191 | .IR epfd . | |
192 | .TP | |
fea681da MK |
193 | .B ENOMEM |
194 | There was insufficient memory to handle the requested | |
195 | .I op | |
196 | control operation. | |
197 | .TP | |
198 | .B EPERM | |
199 | The target file | |
200 | .I fd | |
3d9a2200 | 201 | does not support |
fea681da MK |
202 | .BR epoll . |
203 | .SH CONFORMING TO | |
204 | .BR epoll_ctl (2) | |
205 | is a new API introduced in Linux kernel 2.5.44. | |
206 | The interface should be finalized by Linux kernel 2.5.66. | |
019934ed MK |
207 | .SH BUGS |
208 | In kernel versions before 2.6.9, the | |
209 | .B EPOLL_CTL_DEL | |
210 | operation required a non-NULL pointer in | |
211 | .IR event , | |
212 | even though this argument is ignored. | |
213 | Since kernel 2.6.9, | |
214 | .I event | |
215 | can be specified as NULL | |
216 | when using | |
217 | .BR EPOLL_CTL_DEL . | |
fea681da MK |
218 | .SH "SEE ALSO" |
219 | .BR epoll_create (2), | |
220 | .BR epoll_wait (2), | |
221 | .BR epoll (4) |