1epoll_ctl(2) System Calls Manual epoll_ctl(2)
2
6 epoll_ctl - control interface for an epoll file descriptor
7
9 Standard C library (libc, -lc)
10
12 #include <sys/epoll.h>
13 int epoll_ctl(int epfd, int op, int fd,
15 struct epoll_event *_Nullable event);
16
18 This system call is used to add, modify, or remove entries in the in‐
19 terest list of the epoll(7) instance referred to by the file descriptor
20 epfd. It requests that the operation op be performed for the target
21 file descriptor, fd.
22 Valid values for the op argument are:
24 EPOLL_CTL_ADD
26 Add an entry to the interest list of the epoll file descriptor,
27 epfd. The entry includes the file descriptor, fd, a reference
28 to the corresponding open file description (see epoll(7) and
29 open(2)), and the settings specified in event.
30 EPOLL_CTL_MOD
32 Change the settings associated with fd in the interest list to
33 the new settings specified in event.
34 EPOLL_CTL_DEL
36 Remove (deregister) the target file descriptor fd from the in‐
37 terest list. The event argument is ignored and can be NULL (but
38 see BUGS below).
39 The event argument describes the object linked to the file descriptor
41 fd. The struct epoll_event is described in epoll_event(3type).
42 The data member of the epoll_event structure specifies data that the
44 kernel should save and then return (via epoll_wait(2)) when this file
45 descriptor becomes ready.
46 The events member of the epoll_event structure is a bit mask composed
48 by ORing together zero or more event types, returned by epoll_wait(2),
49 and input flags, which affect its behaviour, but aren't returned. The
50 available event types are:
51 EPOLLIN
53 The associated file is available for read(2) operations.
54 EPOLLOUT
56 The associated file is available for write(2) operations.
57 EPOLLRDHUP (since Linux 2.6.17)
59 Stream socket peer closed connection, or shut down writing half
60 of connection. (This flag is especially useful for writing sim‐
61 ple code to detect peer shutdown when using edge-triggered moni‐
62 toring.)
63 EPOLLPRI
65 There is an exceptional condition on the file descriptor. See
66 the discussion of POLLPRI in poll(2).
67 EPOLLERR
69 Error condition happened on the associated file descriptor.
70 This event is also reported for the write end of a pipe when the
71 read end has been closed.
72 epoll_wait(2) will always report for this event; it is not nec‐
74 essary to set it in events when calling epoll_ctl().
75 EPOLLHUP
77 Hang up happened on the associated file descriptor.
78 epoll_wait(2) will always wait for this event; it is not neces‐
80 sary to set it in events when calling epoll_ctl().
81 Note that when reading from a channel such as a pipe or a stream
83 socket, this event merely indicates that the peer closed its end
84 of the channel. Subsequent reads from the channel will return 0
85 (end of file) only after all outstanding data in the channel has
86 been consumed.
87 And the available input flags are:
89 EPOLLET
91 Requests edge-triggered notification for the associated file de‐
92 scriptor. The default behavior for epoll is level-triggered.
93 See epoll(7) for more detailed information about edge-triggered
94 and level-triggered notification.
95 EPOLLONESHOT (since Linux 2.6.2)
97 Requests one-shot notification for the associated file descrip‐
98 tor. This means that after an event notified for the file de‐
99 scriptor by epoll_wait(2), the file descriptor is disabled in
100 the interest list and no other events will be reported by the
101 epoll interface. The user must call epoll_ctl() with
102 EPOLL_CTL_MOD to rearm the file descriptor with a new event
103 mask.
104 EPOLLWAKEUP (since Linux 3.5)
106 If EPOLLONESHOT and EPOLLET are clear and the process has the
107 CAP_BLOCK_SUSPEND capability, ensure that the system does not
108 enter "suspend" or "hibernate" while this event is pending or
109 being processed. The event is considered as being "processed"
110 from the time when it is returned by a call to epoll_wait(2) un‐
111 til the next call to epoll_wait(2) on the same epoll(7) file de‐
112 scriptor, the closure of that file descriptor, the removal of
113 the event file descriptor with EPOLL_CTL_DEL, or the clearing of
114 EPOLLWAKEUP for the event file descriptor with EPOLL_CTL_MOD.
115 See also BUGS.
116 EPOLLEXCLUSIVE (since Linux 4.5)
118 Sets an exclusive wakeup mode for the epoll file descriptor that
119 is being attached to the target file descriptor, fd. When a
120 wakeup event occurs and multiple epoll file descriptors are at‐
121 tached to the same target file using EPOLLEXCLUSIVE, one or more
122 of the epoll file descriptors will receive an event with
123 epoll_wait(2). The default in this scenario (when EPOLLEXCLU‐
124 SIVE is not set) is for all epoll file descriptors to receive an
125 event. EPOLLEXCLUSIVE is thus useful for avoiding thundering
126 herd problems in certain scenarios.
127 If the same file descriptor is in multiple epoll instances, some
129 with the EPOLLEXCLUSIVE flag, and others without, then events
130 will be provided to all epoll instances that did not specify
131 EPOLLEXCLUSIVE, and at least one of the epoll instances that did
132 specify EPOLLEXCLUSIVE.
133 The following values may be specified in conjunction with
135 EPOLLEXCLUSIVE: EPOLLIN, EPOLLOUT, EPOLLWAKEUP, and EPOLLET.
136 EPOLLHUP and EPOLLERR can also be specified, but this is not re‐
137 quired: as usual, these events are always reported if they oc‐
138 cur, regardless of whether they are specified in events. At‐
139 tempts to specify other values in events yield the error EINVAL.
140 EPOLLEXCLUSIVE may be used only in an EPOLL_CTL_ADD operation;
142 attempts to employ it with EPOLL_CTL_MOD yield an error. If
143 EPOLLEXCLUSIVE has been set using epoll_ctl(), then a subsequent
144 EPOLL_CTL_MOD on the same epfd, fd pair yields an error. A call
145 to epoll_ctl() that specifies EPOLLEXCLUSIVE in events and spec‐
146 ifies the target file descriptor fd as an epoll instance will
147 likewise fail. The error in all of these cases is EINVAL.
148
150 When successful, epoll_ctl() returns zero. When an error occurs,
151 epoll_ctl() returns -1 and errno is set to indicate the error.
152
154 EBADF epfd or fd is not a valid file descriptor.
155 EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is al‐
157 ready registered with this epoll instance.
158 EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd,
160 or the requested operation op is not supported by this inter‐
161 face.
162 EINVAL An invalid event type was specified along with EPOLLEXCLUSIVE in
164 events.
165 EINVAL op was EPOLL_CTL_MOD and events included EPOLLEXCLUSIVE.
167 EINVAL op was EPOLL_CTL_MOD and the EPOLLEXCLUSIVE flag has previously
169 been applied to this epfd, fd pair.
170 EINVAL EPOLLEXCLUSIVE was specified in event and fd refers to an epoll
172 instance.
173 ELOOP fd refers to an epoll instance and this EPOLL_CTL_ADD operation
175 would result in a circular loop of epoll instances monitoring
176 one another or a nesting depth of epoll instances greater than
177 5.
178 ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered
180 with this epoll instance.
181 ENOMEM There was insufficient memory to handle the requested op control
183 operation.
184 ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was en‐
186 countered while trying to register (EPOLL_CTL_ADD) a new file
187 descriptor on an epoll instance. See epoll(7) for further de‐
188 tails.
189 EPERM The target file fd does not support epoll. This error can occur
191 if fd refers to, for example, a regular file or a directory.
192
194 Linux.
195
197 Linux 2.6, glibc 2.3.2.
198
200 The epoll interface supports all file descriptors that support poll(2).
201
203 Before Linux 2.6.9, the EPOLL_CTL_DEL operation required a non-null
204 pointer in event, even though this argument is ignored. Since Linux
205 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL. Appli‐
206 cations that need to be portable to kernels before Linux 2.6.9 should
207 specify a non-null pointer in event.
208 If EPOLLWAKEUP is specified in flags, but the caller does not have the
210 CAP_BLOCK_SUSPEND capability, then the EPOLLWAKEUP flag is silently ig‐
211 nored. This unfortunate behavior is necessary because no validity
212 checks were performed on the flags argument in the original implementa‐
213 tion, and the addition of the EPOLLWAKEUP with a check that caused the
214 call to fail if the caller did not have the CAP_BLOCK_SUSPEND capabil‐
215 ity caused a breakage in at least one existing user-space application
216 that happened to randomly (and uselessly) specify this bit. A robust
217 application should therefore double check that it has the
218 CAP_BLOCK_SUSPEND capability if attempting to use the EPOLLWAKEUP flag.
219
221 epoll_create(2), epoll_wait(2), poll(2), epoll(7)
222Linux man-pages 6.04 2023-04-03 epoll_ctl(2)