1EPOLL_CTL(2)               Linux Programmer's Manual              EPOLL_CTL(2)
2
3
4

NAME

6       epoll_ctl - control interface for an epoll file descriptor
7

SYNOPSIS

9       #include <sys/epoll.h>
10
11       int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
12

DESCRIPTION

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
19       Valid values for the op argument are:
20
21       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
27       EPOLL_CTL_MOD
28              Change  the  settings associated with fd in the interest list to
29              the new settings specified in event.
30
31       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
36       The event argument describes the object linked to the  file  descriptor
37       fd.  The struct epoll_event is defined as:
38
39           typedef union epoll_data {
40               void        *ptr;
41               int          fd;
42               uint32_t     u32;
43               uint64_t     u64;
44           } epoll_data_t;
45
46           struct epoll_event {
47               uint32_t     events;      /* Epoll events */
48               epoll_data_t data;        /* User data variable */
49           };
50
51       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
55       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
58       EPOLLIN
59              The associated file is available for read(2) operations.
60
61       EPOLLOUT
62              The associated file is available for write(2) operations.
63
64       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
70       EPOLLPRI
71              There  is  an exceptional condition on the file descriptor.  See
72              the discussion of POLLPRI in poll(2).
73
74       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
79              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
82       EPOLLHUP
83              Hang up happened on the associated file descriptor.
84
85              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
88              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
94       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
100              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
103       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
112              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
115       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
127              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
130       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
141              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
147              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
155              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
163              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

RETURN VALUE

168       When  successful,  epoll_ctl()  returns  zero.   When  an error occurs,
169       epoll_ctl() returns -1 and errno is set appropriately.
170

ERRORS

172       EBADF  epfd or fd is not a valid file descriptor.
173
174       EEXIST op was EPOLL_CTL_ADD, and the supplied  file  descriptor  fd  is
175              already registered with this epoll instance.
176
177       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
181       EINVAL An invalid event type was specified along with EPOLLEXCLUSIVE in
182              events.
183
184       EINVAL op was EPOLL_CTL_MOD and events included EPOLLEXCLUSIVE.
185
186       EINVAL op was EPOLL_CTL_MOD and the EPOLLEXCLUSIVE flag has  previously
187              been applied to this epfd, fd pair.
188
189       EINVAL EPOLLEXCLUSIVE  was specified in event and fd refers to an epoll
190              instance.
191
192       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
196       ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not  registered
197              with this epoll instance.
198
199       ENOMEM There was insufficient memory to handle the requested op control
200              operation.
201
202       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
207       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

VERSIONS

211       epoll_ctl() was added to the kernel in version 2.6.
212

CONFORMING TO

214       epoll_ctl() is Linux-specific.  Library support is  provided  in  glibc
215       starting with version 2.3.2.
216

NOTES

218       The epoll interface supports all file descriptors that support poll(2).
219

BUGS

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
227       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

SEE ALSO

239       epoll_create(2), epoll_wait(2), poll(2), epoll(7)
240

COLOPHON

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/.
246
247
248
249Linux                             2020-04-11                      EPOLL_CTL(2)
Impressum