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