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