]>
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 | .\" |
67d2c687 | 20 | .TH EPOLL_CTL 2 2015-05-07 "Linux" "Linux Programmer's Manual" |
fea681da | 21 | .SH NAME |
d9cb0d7d | 22 | epoll_ctl \- control interface for an epoll file descriptor |
fea681da MK |
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 | |
e87feb33 | 41 | argument are: |
7829230a MK |
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 |
e87feb33 | 78 | is defined as: |
fea681da | 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 | |
03323a99 | 98 | member is a bit mask 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 . | |
ea735ea8 MK |
133 | Note that when reading from a channel such as a pipe or a stream socket, |
134 | this event merely indicates that the peer closed its end of the channel. | |
135 | Subsequent reads from the channel will return 0 (end of file) | |
136 | only after all outstanding data in the channel has been consumed. | |
fea681da MK |
137 | .TP |
138 | .B EPOLLET | |
d9bfdb9c MK |
139 | Sets the Edge Triggered behavior for the associated file descriptor. |
140 | The default behavior for | |
fea681da | 141 | .B epoll |
c13182ef MK |
142 | is Level Triggered. |
143 | See | |
2315114c | 144 | .BR epoll (7) |
704a18f0 | 145 | for more detailed information about Edge and Level Triggered event |
fea681da MK |
146 | distribution architectures. |
147 | .TP | |
64d6219c | 148 | .BR EPOLLONESHOT " (since Linux 2.6.2)" |
d9bfdb9c | 149 | Sets the one-shot behavior for the associated file descriptor. |
019934ed | 150 | This means that after an event is pulled out with |
fea681da MK |
151 | .BR epoll_wait (2) |
152 | the associated file descriptor is internally disabled and no other events | |
153 | will be reported by the | |
154 | .B epoll | |
c13182ef MK |
155 | interface. |
156 | The user must call | |
2777b1ca | 157 | .BR epoll_ctl () |
fea681da MK |
158 | with |
159 | .B EPOLL_CTL_MOD | |
3b777aff | 160 | to rearm the file descriptor with a new event mask. |
573f05ef N |
161 | .TP |
162 | .BR EPOLLWAKEUP " (since Linux 3.5)" | |
1bc86e8a | 163 | .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 |
573f05ef N |
164 | If |
165 | .B EPOLLONESHOT | |
166 | and | |
167 | .B EPOLLET | |
168 | are clear and the process has the | |
169 | .B CAP_BLOCK_SUSPEND | |
1bc86e8a | 170 | capability, |
573f05ef N |
171 | ensure that the system does not enter "suspend" or |
172 | "hibernate" while this event is pending or being processed. | |
1bc86e8a MK |
173 | The event is considered as being "processed" from the time |
174 | when it is returned by a call to | |
573f05ef N |
175 | .BR epoll_wait (2) |
176 | until the next call to | |
177 | .BR epoll_wait (2) | |
178 | on the same | |
179 | .BR epoll (7) | |
c835f12b N |
180 | file descriptor, |
181 | the closure of that file descriptor, | |
182 | the removal of the event file descriptor with | |
183 | .BR EPOLL_CTL_DEL , | |
184 | or the clearing of | |
185 | .B EPOLLWAKEUP | |
186 | for the event file descriptor with | |
187 | .BR EPOLL_CTL_MOD . | |
8ab32b47 | 188 | See also BUGS. |
47297adb | 189 | .SH RETURN VALUE |
c13182ef | 190 | When successful, |
2777b1ca | 191 | .BR epoll_ctl () |
c13182ef MK |
192 | returns zero. |
193 | When an error occurs, | |
2777b1ca | 194 | .BR epoll_ctl () |
fea681da MK |
195 | returns \-1 and |
196 | .I errno | |
197 | is set appropriately. | |
198 | .SH ERRORS | |
199 | .TP | |
200 | .B EBADF | |
fea681da | 201 | .I epfd |
2cfa66cf MK |
202 | or |
203 | .I fd | |
3d9a2200 MK |
204 | is not a valid file descriptor. |
205 | .TP | |
206 | .B EEXIST | |
207 | .I op | |
682edefb MK |
208 | was |
209 | .BR EPOLL_CTL_ADD , | |
210 | and the supplied file descriptor | |
0daa9e92 | 211 | .I fd |
a58b3360 | 212 | is already registered with this epoll instance. |
fea681da MK |
213 | .TP |
214 | .B EINVAL | |
0daa9e92 | 215 | .I epfd |
fea681da MK |
216 | is not an |
217 | .B epoll | |
3d9a2200 MK |
218 | file descriptor, |
219 | or | |
0daa9e92 | 220 | .I fd |
3d9a2200 MK |
221 | is the same as |
222 | .IR epfd , | |
223 | or the requested operation | |
fea681da MK |
224 | .I op |
225 | is not supported by this interface. | |
226 | .TP | |
813596e5 MK |
227 | .B ELOOP |
228 | .I fd | |
229 | refers to an epoll instance and this | |
230 | .B EPOLL_CTL_ADD | |
231 | operation would result in a circular loop of epoll instances | |
232 | monitoring one another. | |
233 | .TP | |
3d9a2200 MK |
234 | .B ENOENT |
235 | .I op | |
682edefb | 236 | was |
0daa9e92 | 237 | .B EPOLL_CTL_MOD |
682edefb MK |
238 | or |
239 | .BR EPOLL_CTL_DEL , | |
240 | and | |
0daa9e92 | 241 | .I fd |