]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Davide Libenzi |
4366109b | 2 | .\" Davide Libenzi <davidel@xmailserver.org> |
fea681da | 3 | .\" |
f0008367 | 4 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
fea681da MK |
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 | .\" | |
68fa4398 MK |
15 | .\" You should have received a copy of the GNU General Public |
16 | .\" License along with this manual; if not, see | |
17 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 18 | .\" %%%LICENSE_END |
fea681da | 19 | .\" |
78d1cbde | 20 | .TH EPOLL_CTL 2 2012-04-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
21 | .SH NAME |
22 | epoll_ctl \- control interface for an epoll descriptor | |
23 | .SH SYNOPSIS | |
24 | .B #include <sys/epoll.h> | |
25 | .sp | |
52e87bbe MK |
26 | .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \ |
27 | ", struct epoll_event *" event ); | |
fea681da | 28 | .SH DESCRIPTION |
78d1cbde MK |
29 | This system call performs control operations on the |
30 | .BR epoll (7) | |
31 | instance | |
a58b3360 MK |
32 | referred to by the file descriptor |
33 | .IR epfd . | |
34 | It requests that the operation | |
0daa9e92 | 35 | .I op |
7829230a | 36 | be performed for the target file descriptor, |
fea681da | 37 | .IR fd . |
7829230a MK |
38 | |
39 | Valid values for the | |
40 | .I op | |
41 | argument are : | |
42 | .TP | |
43 | .B EPOLL_CTL_ADD | |
44 | Register the target file descriptor | |
45 | .I fd | |
46 | on the | |
47 | .B epoll | |
48 | instance referred to by the file descriptor | |
49 | .I epfd | |
50 | and associate the event | |
51 | .I event | |
52 | with the internal file linked to | |
53 | .IR fd . | |
54 | .TP | |
55 | .B EPOLL_CTL_MOD | |
56 | Change the event | |
57 | .I event | |
58 | associated with the target file descriptor | |
59 | .IR fd . | |
60 | .TP | |
61 | .B EPOLL_CTL_DEL | |
62 | Remove (deregister) the target file descriptor | |
63 | .I fd | |
64 | from the | |
65 | .B epoll | |
66 | instance referred to by | |
67 | .IR epfd . | |
68 | The | |
69 | .I event | |
70 | is ignored and can be NULL (but see BUGS below). | |
71 | .PP | |
fea681da | 72 | The |
0daa9e92 | 73 | .I event |
7829230a | 74 | argument describes the object linked to the file descriptor |
fea681da MK |
75 | .IR fd . |
76 | The | |
8478ee02 | 77 | .I struct epoll_event |
fea681da MK |
78 | is defined as : |
79 | .sp | |
a08ea57c | 80 | .in +4n |
fea681da | 81 | .nf |
cf0a9ace | 82 | typedef union epoll_data { |
6ebde978 MK |
83 | void *ptr; |
84 | int fd; | |
2677bc5c MK |
85 | uint32_t u32; |
86 | uint64_t u64; | |
cf0a9ace | 87 | } epoll_data_t; |
fea681da | 88 | |
cf0a9ace | 89 | struct epoll_event { |
2677bc5c | 90 | uint32_t events; /* Epoll events */ |
6ebde978 | 91 | epoll_data_t data; /* User data variable */ |
cf0a9ace | 92 | }; |
fea681da | 93 | .fi |
a08ea57c | 94 | .in |
fea681da MK |
95 | |
96 | The | |
97 | .I events | |
98 | member is a bit set composed using the following available event | |
c781c53c | 99 | types: |
fea681da MK |
100 | .TP |
101 | .B EPOLLIN | |
102 | The associated file is available for | |
103 | .BR read (2) | |
104 | operations. | |
105 | .TP | |
106 | .B EPOLLOUT | |
107 | The associated file is available for | |
108 | .BR write (2) | |
109 | operations. | |
110 | .TP | |
64d6219c | 111 | .BR EPOLLRDHUP " (since Linux 2.6.17)" |
c13182ef | 112 | Stream socket peer closed connection, |
04706fd7 | 113 | or shut down writing half of connection. |
c13182ef | 114 | (This flag is especially useful for writing simple code to detect |
04706fd7 MK |
115 | peer shutdown when using Edge Triggered monitoring.) |
116 | .TP | |
fea681da MK |
117 | .B EPOLLPRI |
118 | There is urgent data available for | |
119 | .BR read (2) | |
120 | operations. | |
121 | .TP | |
122 | .B EPOLLERR | |
123 | Error condition happened on the associated file descriptor. | |
3d9a2200 MK |
124 | .BR epoll_wait (2) |
125 | will always wait for this event; it is not necessary to set it in | |
126 | .IR events . | |
fea681da MK |
127 | .TP |
128 | .B EPOLLHUP | |
129 | Hang up happened on the associated file descriptor. | |
3d9a2200 MK |
130 | .BR epoll_wait (2) |
131 | will always wait for this event; it is not necessary to set it in | |
132 | .IR events . | |
fea681da MK |
133 | .TP |
134 | .B EPOLLET | |
d9bfdb9c MK |
135 | Sets the Edge Triggered behavior for the associated file descriptor. |
136 | The default behavior for | |
fea681da | 137 | .B epoll |
c13182ef MK |
138 | is Level Triggered. |
139 | See | |
2315114c | 140 | .BR epoll (7) |
704a18f0 | 141 | for more detailed information about Edge and Level Triggered event |
fea681da MK |
142 | distribution architectures. |
143 | .TP | |
64d6219c | 144 | .BR EPOLLONESHOT " (since Linux 2.6.2)" |
d9bfdb9c | 145 | Sets the one-shot behavior for the associated file descriptor. |
019934ed | 146 | This means that after an event is pulled out with |
fea681da MK |
147 | .BR epoll_wait (2) |
148 | the associated file descriptor is internally disabled and no other events | |
149 | will be reported by the | |
150 | .B epoll | |
c13182ef MK |
151 | interface. |
152 | The user must call | |
2777b1ca | 153 | .BR epoll_ctl () |
fea681da MK |
154 | with |
155 | .B EPOLL_CTL_MOD | |
3b777aff | 156 | to rearm the file descriptor with a new event mask. |
573f05ef N |
157 | .TP |
158 | .BR EPOLLWAKEUP " (since Linux 3.5)" | |
159 | If | |
160 | .B EPOLLONESHOT | |
161 | and | |
162 | .B EPOLLET | |
163 | are clear and the process has the | |
164 | .B CAP_BLOCK_SUSPEND | |
165 | .BR capability (7), | |
166 | ensure that the system does not enter "suspend" or | |
167 | "hibernate" while this event is pending or being processed. | |
168 | The event is considered as being "processed" from when it returned by | |
169 | a call to | |
170 | .BR epoll_wait (2) | |
171 | until the next call to | |
172 | .BR epoll_wait (2) | |
173 | on the same | |
174 | .BR epoll (7) | |
175 | file descriptor. | |
176 | .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 | |
47297adb | 177 | .SH RETURN VALUE |
c13182ef | 178 | When successful, |
2777b1ca | 179 | .BR epoll_ctl () |
c13182ef MK |
180 | returns zero. |
181 | When an error occurs, | |
2777b1ca | 182 | .BR epoll_ctl () |
fea681da MK |
183 | returns \-1 and |
184 | .I errno | |
185 | is set appropriately. | |
186 | .SH ERRORS | |
187 | .TP | |
188 | .B EBADF | |
fea681da | 189 | .I epfd |
2cfa66cf MK |
190 | or |
191 | .I fd | |
3d9a2200 MK |
192 | is not a valid file descriptor. |
193 | .TP | |
194 | .B EEXIST | |
195 | .I op | |
682edefb MK |
196 | was |
197 | .BR EPOLL_CTL_ADD , | |
198 | and the supplied file descriptor | |
0daa9e92 | 199 | .I fd |
a58b3360 | 200 | is already registered with this epoll instance. |
fea681da MK |
201 | .TP |
202 | .B EINVAL | |
0daa9e92 | 203 | .I epfd |
fea681da MK |
204 | is not an |
205 | .B epoll | |
3d9a2200 MK |
206 | file descriptor, |
207 | or | |
0daa9e92 | 208 | .I fd |
3d9a2200 MK |
209 | is the same as |
210 | .IR epfd , | |
211 | or the requested operation | |
fea681da MK |
212 | .I op |
213 | is not supported by this interface. | |
214 | .TP | |
3d9a2200 MK |
215 | .B ENOENT |
216 | .I op | |
682edefb | 217 | was |
0daa9e92 | 218 | .B EPOLL_CTL_MOD |
682edefb MK |
219 | or |
220 | .BR EPOLL_CTL_DEL , | |
221 | and | |
0daa9e92 | 222 | .I fd |