]>
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 | |
28 | .BR "int epoll_ctl(int " epfd ", int " op ", int " fd ", struct epoll_event *" event ) | |
29 | .SH DESCRIPTION | |
30 | Control an | |
31 | .B epoll | |
32 | descriptor, | |
33 | .IR epfd , | |
34 | by requesting the operation | |
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 | |
43 | .B struct epoll_event | |
44 | is defined as : | |
45 | .sp | |
46 | .nf | |
47 | ||
48 | typedef union epoll_data { | |
49 | void *ptr; | |
50 | int fd; | |
51 | __uint32_t u32; | |
52 | __uint64_t u64; | |
53 | } epoll_data_t; | |
54 | ||
55 | struct epoll_event { | |
56 | __uint32_t events; /* Epoll events */ | |
57 | epoll_data_t data; /* User data variable */ | |
58 | }; | |
59 | ||
60 | .fi | |
61 | ||
62 | The | |
63 | .I events | |
64 | member is a bit set composed using the following available event | |
65 | types : | |
66 | .TP | |
67 | .B EPOLLIN | |
68 | The associated file is available for | |
69 | .BR read (2) | |
70 | operations. | |
71 | .TP | |
72 | .B EPOLLOUT | |
73 | The associated file is available for | |
74 | .BR write (2) | |
75 | operations. | |
76 | .TP | |
77 | .B EPOLLPRI | |
78 | There is urgent data available for | |
79 | .BR read (2) | |
80 | operations. | |
81 | .TP | |
82 | .B EPOLLERR | |
83 | Error condition happened on the associated file descriptor. | |
3d9a2200 MK |
84 | .BR epoll_wait (2) |
85 | will always wait for this event; it is not necessary to set it in | |
86 | .IR events . | |
fea681da MK |
87 | .TP |
88 | .B EPOLLHUP | |
89 | Hang up happened on the associated file descriptor. | |
3d9a2200 MK |
90 | .BR epoll_wait (2) |
91 | will always wait for this event; it is not necessary to set it in | |
92 | .IR events . | |
fea681da MK |
93 | .TP |
94 | .B EPOLLET | |
95 | Sets the Edge Triggered behaviour for the associated file descriptor. | |
96 | The default behaviour for | |
97 | .B epoll | |
98 | is Level Triggered. See | |
99 | .BR epoll (4) | |
100 | for more detailed informations about Edge and Level Triggered event | |
101 | distribution architectures. | |
102 | .TP | |
103 | .B EPOLLONESHOT | |
104 | Sets the One-Shot behaviour for the associated file descriptor. It means | |
105 | that after an event is pulled out with | |
106 | .BR epoll_wait (2) | |
107 | the associated file descriptor is internally disabled and no other events | |
108 | will be reported by the | |
109 | .B epoll | |
110 | interface. The user must call | |
111 | .BR epoll_ctl (2) | |
112 | with | |
113 | .B EPOLL_CTL_MOD | |
114 | to re-enable the file descriptor with a new event mask. | |
115 | .PP | |
116 | .sp | |
117 | The | |
118 | .B epoll | |
119 | interface supports all file descriptors that support | |
120 | .BR poll (2). | |
121 | Valid values for the | |
122 | .IR op | |
123 | parameter are : | |
124 | .RS | |
125 | .TP | |
126 | .B EPOLL_CTL_ADD | |
127 | Add the target file descriptor | |
128 | .I fd | |
129 | to the | |
130 | .B epoll | |
131 | descriptor | |
132 | .I epfd | |
133 | and associate the event | |
134 | .I event | |
135 | with the internal file linked to | |
136 | .IR fd . | |
137 | .TP | |
138 | .B EPOLL_CTL_MOD | |
139 | Change the event | |
140 | .I event | |
99d2b7a2 | 141 | associated with the target file descriptor |
fea681da MK |
142 | .IR fd . |
143 | .TP | |
144 | .B EPOLL_CTL_DEL | |
145 | Remove the target file descriptor | |
146 | .I fd | |
147 | from the | |
148 | .B epoll | |
149 | file descriptor, | |
150 | .IR epfd . | |
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. | |
207 | .SH "SEE ALSO" | |
208 | .BR epoll_create (2), | |
209 | .BR epoll_wait (2), | |
210 | .BR epoll (4) |