1EPOLL_CTL(2) Linux Programmer's Manual EPOLL_CTL(2)
2
6 epoll_ctl - control interface for an epoll file descriptor
7
9 #include <sys/epoll.h>
10 int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
12
14 This system call is used to add, modify, or remove entries in the
15 interest list of the epoll(7) instance referred to by the file descrip‐
16 tor epfd. It requests that the operation op be performed for the tar‐
17 get file descriptor, fd.
18 Valid values for the op argument are:
20 EPOLL_CTL_ADD
22 Add an entry to the interest list of the epoll file descriptor,
23 epfd. The entry includes the file descriptor, fd, a reference
24 to the corresponding open file description (see epoll(7) and
25 open(2)), and the settings specified in event.
26 EPOLL_CTL_MOD
28 Change the settings associated with fd in the interest list to
29 the new settings specified in event.
30 EPOLL_CTL_DEL
32 Remove (deregister) the target file descriptor fd from the
33 interest list. The event argument is ignored and can be NULL
34 (but see BUGS below).
35 The event argument describes the object linked to the file descriptor
37 fd. The struct epoll_event is defined as:
38 typedef union epoll_data {
40 void *ptr;
41 int fd;
42 uint32_t u32;
43 uint64_t u64;
44 } epoll_data_t;
45 struct epoll_event {
47 uint32_t events; /* Epoll events */
48 epoll_data_t data; /* User data variable */
49 };
50 The data member of the epoll_event structure specifies data that the
52 kernel should save and then return (via epoll_wait(2)) when this file
53 descriptor becomes ready.
54 The events member of the epoll_event structure is a bit mask composed
56 by ORing together zero or more of the following available event types:
57 EPOLLIN
59 The associated file is available for read(2) operations.
60 EPOLLOUT
62 The associated file is available for write(2) operations.
63 EPOLLRDHUP (since Linux 2.6.17)
65 Stream socket peer closed connection, or shut down writing half
66 of connection. (This flag is especially useful for writing sim‐
67 ple code to detect peer shutdown when using edge-triggered moni‐
68 toring.)
69 EPOLLPRI
71 There is an exceptional condition on the file descriptor. See
72 the discussion of POLLPRI in poll(2).
73 EPOLLERR
75 Error condition happened on the associated file descriptor.
76 This event is also reported for the write end of a pipe when the
77 read end has been closed.
78 epoll_wait(2) will always report for this event; it is not nec‐
80 essary to set it in events when calling epoll_ctl().
81 EPOLLHUP
83 Hang up happened on the associated file descriptor.
84 epoll_wait(2) will always wait for this event; it is not neces‐
86 sary to set it in events when calling epoll_ctl().
87 Note that when reading from a channel such as a pipe or a stream
89 socket, this event merely indicates that the peer closed its end
90 of the channel. Subsequent reads from the channel will return 0
91 (end of file) only after all outstanding data in the channel has
92 been consumed.
93 EPOLLET
95 Requests edge-triggered notification for the associated file
96 descriptor. The default behavior for epoll is level-triggered.
97 See epoll(7) for more detailed information about edge-triggered
98 and level-triggered notification.
99 This flag is an input flag for the event.events field when call‐
101 ing epoll_ctl(); it is never returned by epoll_wait(2).
102 EPOLLONESHOT (since Linux 2.6.2)
104 Requests one-shot notification for the associated file descrip‐
105 tor. This means that after an event notified for the file
106 descriptor by epoll_wait(2), the file descriptor is disabled in
107 the interest list and no other events will be reported by the
108 epoll interface. The user must call epoll_ctl() with
109 EPOLL_CTL_MOD to rearm the file descriptor with a new event
110 mask.
111 This flag is an input flag for the event.events field when call‐
113 ing epoll_ctl(); it is never returned by epoll_wait(2).
114 EPOLLWAKEUP (since Linux 3.5)
116 If EPOLLONESHOT and EPOLLET are clear and the process has the
117 CAP_BLOCK_SUSPEND capability, ensure that the system does not
118 enter "suspend" or "hibernate" while this event is pending or
119 being processed. The event is considered as being "processed"
120 from the time when it is returned by a call to epoll_wait(2)
121 until the next call to epoll_wait(2) on the same epoll(7) file
122 descriptor, the closure of that file descriptor, the removal of
123 the event file descriptor with EPOLL_CTL_DEL, or the clearing of
124 EPOLLWAKEUP for the event file descriptor with EPOLL_CTL_MOD.
125 See also BUGS.
126 This flag is an input flag for the event.events field when call‐
128 ing epoll_ctl(); it is never returned by epoll_wait(2).
129 EPOLLEXCLUSIVE (since Linux 4.5)
131 Sets an exclusive wakeup mode for the epoll file descriptor that
132 is being attached to the target file descriptor, fd. When a
133 wakeup event occurs and multiple epoll file descriptors are
134 attached to the same target file using EPOLLEXCLUSIVE, one or
135 more of the epoll file descriptors will receive an event with
136 epoll_wait(2). The default in this scenario (when EPOLLEXCLU‐
137 SIVE is not set) is for all epoll file descriptors to receive an
138 event. EPOLLEXCLUSIVE is thus useful for avoiding thundering
139 herd problems in certain scenarios.
140 If the same file descriptor is in multiple epoll instances, some
142 with the EPOLLEXCLUSIVE flag, and others without, then events
143 will be provided to all epoll instances that did not specify
144 EPOLLEXCLUSIVE, and at least one of the epoll instances that did
145 specify EPOLLEXCLUSIVE.
146 The following values may be specified in conjunction with
148 EPOLLEXCLUSIVE: EPOLLIN, EPOLLOUT, EPOLLWAKEUP, and EPOLLET.
149 EPOLLHUP and EPOLLERR can also be specified, but this is not
150 required: as usual, these events are always reported if they
151 occur, regardless of whether they are specified in events.
152 Attempts to specify other values in events yield the error EIN‐
153 VAL.
154 EPOLLEXCLUSIVE may be used only in an EPOLL_CTL_ADD operation;
156 attempts to employ it with EPOLL_CTL_MOD yield an error. If
157 EPOLLEXCLUSIVE has been set using epoll_ctl(), then a subsequent
158 EPOLL_CTL_MOD on the same epfd, fd pair yields an error. A call
159 to epoll_ctl() that specifies EPOLLEXCLUSIVE in events and spec‐
160 ifies the target file descriptor fd as an epoll instance will
161 likewise fail. The error in all of these cases is EINVAL.
162 The EPOLLEXCLUSIVE flag is an input flag for the event.events
164 field when calling epoll_ctl(); it is never returned by
165 epoll_wait(2).
166
168 When successful, epoll_ctl() returns zero. When an error occurs,
169 epoll_ctl() returns -1 and errno is set appropriately.
170
172 EBADF epfd or fd is not a valid file descriptor.
173 EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is
175 already registered with this epoll instance.
176 EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd,
178 or the requested operation op is not supported by this inter‐
179 face.
180 EINVAL An invalid event type was specified along with EPOLLEXCLUSIVE in
182 events.
183 EINVAL op was EPOLL_CTL_MOD and events included EPOLLEXCLUSIVE.
185 EINVAL op was EPOLL_CTL_MOD and the EPOLLEXCLUSIVE flag has previously
187 been applied to this epfd, fd pair.
188 EINVAL EPOLLEXCLUSIVE was specified in event and fd refers to an epoll
190 instance.
191 ELOOP fd refers to an epoll instance and this EPOLL_CTL_ADD operation
193 would result in a circular loop of epoll instances monitoring
194 one another.
195 ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered
197 with this epoll instance.
198 ENOMEM There was insufficient memory to handle the requested op control
200 operation.
201 ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was
203 encountered while trying to register (EPOLL_CTL_ADD) a new file
204 descriptor on an epoll instance. See epoll(7) for further
205 details.
206 EPERM The target file fd does not support epoll. This error can occur
208 if fd refers to, for example, a regular file or a directory.
209
211 epoll_ctl() was added to the kernel in version 2.6.
212
214 epoll_ctl() is Linux-specific. Library support is provided in glibc
215 starting with version 2.3.2.
216
218 The epoll interface supports all file descriptors that support poll(2).
219
221 In kernel versions before 2.6.9, the EPOLL_CTL_DEL operation required a
222 non-null pointer in event, even though this argument is ignored. Since
223 Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL.
224 Applications that need to be portable to kernels before 2.6.9 should
225 specify a non-null pointer in event.
226 If EPOLLWAKEUP is specified in flags, but the caller does not have the
228 CAP_BLOCK_SUSPEND capability, then the EPOLLWAKEUP flag is silently
229 ignored. This unfortunate behavior is necessary because no validity
230 checks were performed on the flags argument in the original implementa‐
231 tion, and the addition of the EPOLLWAKEUP with a check that caused the
232 call to fail if the caller did not have the CAP_BLOCK_SUSPEND capabil‐
233 ity caused a breakage in at least one existing user-space application
234 that happened to randomly (and uselessly) specify this bit. A robust
235 application should therefore double check that it has the
236 CAP_BLOCK_SUSPEND capability if attempting to use the EPOLLWAKEUP flag.
237
239 epoll_create(2), epoll_wait(2), poll(2), epoll(7)
240
242 This page is part of release 5.07 of the Linux man-pages project. A
243 description of the project, information about reporting bugs, and the
244 latest version of this page, can be found at
245 https://www.kernel.org/doc/man-pages/.
246Linux 2020-04-11 EPOLL_CTL(2)