man2/epoll_ctl.2

   1 .\"  Copyright (C) 2003  Davide Libenzi
   2 .\"  Davide Libenzi <davidel@xmailserver.org>
   3 .\" and Copyright 2009, 2014, 2016, 2018, 2019 Michael Kerrisk <tk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .TH EPOLL_CTL 2 2021-03-22 "Linux man-pages (unreleased)"
   8 .SH NAME
   9 epoll_ctl \- control interface for an epoll file descriptor
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <sys/epoll.h>
  16 .PP
  17 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
  18 ", struct epoll_event *" event );
  19 .fi
  20 .SH DESCRIPTION
  21 This system call is used to add, modify, or remove
  22 entries in the interest list of the
  23 .BR epoll (7)
  24 instance
  25 referred to by the file descriptor
  26 .IR epfd .
  27 It requests that the operation
  28 .I op
  29 be performed for the target file descriptor,
  30 .IR fd .
  31 .PP
  32 Valid values for the
  33 .I op
  34 argument are:
  35 .TP
  36 .B EPOLL_CTL_ADD
  37 Add an entry to the interest list of the epoll file descriptor,
  38 .IR epfd .
  39 The entry includes the file descriptor,
  40 .IR fd ,
  41 a reference to the corresponding open file description (see
  42 .BR epoll (7)
  43 and
  44 .BR open (2)),
  45 and the settings specified in
  46 .IR event .
  47 .TP
  48 .B EPOLL_CTL_MOD
  49 Change the settings associated with
  50 .I fd
  51 in the interest list to the new settings specified in
  52 .IR event .
  53 .TP
  54 .B EPOLL_CTL_DEL
  55 Remove (deregister) the target file descriptor
  56 .I fd
  57 from the interest list.
  58 The
  59 .I event
  60 argument is ignored and can be NULL (but see BUGS below).
  61 .PP
  62 The
  63 .I event
  64 argument describes the object linked to the file descriptor
  65 .IR fd .
  66 The
  67 .I struct epoll_event
  68 is described in
  69 .BR epoll_event (3type).
  70 .PP
  71 The
  72 .I data
  73 member of the
  74 .I epoll_event
  75 structure specifies data that the kernel should save and then return (via
  76 .BR epoll_wait (2))
  77 when this file descriptor becomes ready.
  78 .PP
  79 The
  80 .I events
  81 member of the
  82 .I epoll_event
  83 structure is a bit mask composed by ORing together zero or more event types,
  84 returned by
  85 .BR epoll_wait (2),
  86 and input flags, which affect its behaviour, but aren't returned.
  87 The available event types are:
  88 .TP
  89 .B EPOLLIN
  90 The associated file is available for
  91 .BR read (2)
  92 operations.
  93 .TP
  94 .B EPOLLOUT
  95 The associated file is available for
  96 .BR write (2)
  97 operations.
  98 .TP
  99 .BR EPOLLRDHUP " (since Linux 2.6.17)"
 100 Stream socket peer closed connection,
 101 or shut down writing half of connection.
 102 (This flag is especially useful for writing simple code to detect
 103 peer shutdown when using edge-triggered monitoring.)
 104 .TP
 105 .B EPOLLPRI
 106 There is an exceptional condition on the file descriptor.
 107 See the discussion of
 108 .B POLLPRI
 109 in
 110 .BR poll (2).
 111 .TP
 112 .B EPOLLERR
 113 Error condition happened on the associated file descriptor.
 114 This event is also reported for the write end of a pipe when the read end
 115 has been closed.
 116 .IP
 117 .BR epoll_wait (2)
 118 will always report for this event; it is not necessary to set it in
 119 .I events
 120 when calling
 121 .BR epoll_ctl ().
 122 .TP
 123 .B EPOLLHUP
 124 Hang up happened on the associated file descriptor.
 125 .IP
 126 .BR epoll_wait (2)
 127 will always wait for this event; it is not necessary to set it in
 128 .I events
 129 when calling
 130 .BR epoll_ctl ().
 131 .IP
 132 Note that when reading from a channel such as a pipe or a stream socket,
 133 this event merely indicates that the peer closed its end of the channel.
 134 Subsequent reads from the channel will return 0 (end of file)
 135 only after all outstanding data in the channel has been consumed.
 136 .PP
 137 And the available input flags are:
 138 .TP
 139 .B EPOLLET
 140 Requests edge-triggered notification for the associated file descriptor.
 141 The default behavior for
 142 .B epoll
 143 is level-triggered.
 144 See
 145 .BR epoll (7)
 146 for more detailed information about edge-triggered and
 147 level-triggered notification.
 148 .TP
 149 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 150 Requests one-shot notification for the associated file descriptor.
 151 This means that after an event notified for the file descriptor by
 152 .BR epoll_wait (2),
 153 the file descriptor is disabled in the interest list and no other events
 154 will be reported by the
 155 .B epoll
 156 interface.
 157 The user must call
 158 .BR epoll_ctl ()
 159 with
 160 .B EPOLL_CTL_MOD
 161 to rearm the file descriptor with a new event mask.
 162 .TP
 163 .BR EPOLLWAKEUP " (since Linux 3.5)"
 164 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
 165 If
 166 .B EPOLLONESHOT
 167 and
 168 .B EPOLLET
 169 are clear and the process has the
 170 .B CAP_BLOCK_SUSPEND
 171 capability,
 172 ensure that the system does not enter "suspend" or
 173 "hibernate" while this event is pending or being processed.
 174 The event is considered as being "processed" from the time
 175 when it is returned by a call to
 176 .BR epoll_wait (2)
 177 until the next call to
 178 .BR epoll_wait (2)
 179 on the same
 180 .BR epoll (7)
 181 file descriptor,
 182 the closure of that file descriptor,
 183 the removal of the event file descriptor with
 184 .BR EPOLL_CTL_DEL ,
 185 or the clearing of
 186 .B EPOLLWAKEUP
 187 for the event file descriptor with
 188 .BR EPOLL_CTL_MOD .
 189 See also BUGS.
 190 .TP
 191 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
 192 Sets an exclusive wakeup mode for the epoll file descriptor that is being
 193 attached to the target file descriptor,
 194 .IR fd .
 195 When a wakeup event occurs and multiple epoll file descriptors
 196 are attached to the same target file using
 197 .BR EPOLLEXCLUSIVE ,
 198 one or more of the epoll file descriptors will receive an event with
 199 .BR epoll_wait (2).
 200 The default in this scenario (when
 201 .B EPOLLEXCLUSIVE
 202 is not set) is for all epoll file descriptors to receive an event.
 203 .B EPOLLEXCLUSIVE
 204 is thus useful for avoiding thundering herd problems in certain scenarios.
 205 .IP
 206 If the same file descriptor is in multiple epoll instances,
 207 some with the
 208 .B EPOLLEXCLUSIVE
 209 flag, and others without, then events will be provided to all epoll
 210 instances that did not specify
 211 .BR EPOLLEXCLUSIVE ,
 212 and at least one of the epoll instances that did specify
 213 .BR EPOLLEXCLUSIVE .
 214 .IP
 215 The following values may be specified in conjunction with
 216 .BR EPOLLEXCLUSIVE :
 217 .BR EPOLLIN ,
 218 .BR EPOLLOUT ,
 219 .BR EPOLLWAKEUP ,
 220 and
 221 .BR EPOLLET .
 222 .B EPOLLHUP
 223 and
 224 .B EPOLLERR
 225 can also be specified, but this is not required:
 226 as usual, these events are always reported if they occur,
 227 regardless of whether they are specified in
 228 .IR events .
 229 Attempts to specify other values in
 230 .I events
 231 yield the error
 232 .BR EINVAL .
 233 .IP
 234 .B EPOLLEXCLUSIVE
 235 may be used only in an
 236 .B EPOLL_CTL_ADD
 237 operation; attempts to employ it with
 238 .B EPOLL_CTL_MOD
 239 yield an error.
 240 If
 241 .B EPOLLEXCLUSIVE
 242 has been set using
 243 .BR epoll_ctl (),
 244 then a subsequent
 245 .B EPOLL_CTL_MOD
 246 on the same
 247 .IR epfd ,\~ fd
 248 pair yields an error.
 249 A call to
 250 .BR epoll_ctl ()
 251 that specifies
 252 .B EPOLLEXCLUSIVE
 253 in
 254 .I events
 255 and specifies the target file descriptor
 256 .I fd
 257 as an epoll instance will likewise fail.
 258 The error in all of these cases is
 259 .BR EINVAL .
 260 .SH RETURN VALUE
 261 When successful,
 262 .BR epoll_ctl ()
 263 returns zero.
 264 When an error occurs,
 265 .BR epoll_ctl ()
 266 returns \-1 and
 267 .I errno
 268 is set to indicate the error.
 269 .SH ERRORS
 270 .TP
 271 .B EBADF
 272 .I epfd
 273 or
 274 .I fd
 275 is not a valid file descriptor.
 276 .TP
 277 .B EEXIST
 278 .I op
 279 was
 280 .BR EPOLL_CTL_ADD ,
 281 and the supplied file descriptor
 282 .I fd
 283 is already registered with this epoll instance.
 284 .TP
 285 .B EINVAL
 286 .I epfd
 287 is not an
 288 .B epoll
 289 file descriptor,
 290 or
 291 .I fd
 292 is the same as
 293 .IR epfd ,
 294 or the requested operation
 295 .I op
 296 is not supported by this interface.
 297 .TP
 298 .B EINVAL
 299 An invalid event type was specified along with
 300 .B EPOLLEXCLUSIVE
 301 in
 302 .IR events .
 303 .TP
 304 .B EINVAL
 305 .I op
 306 was
 307 .B EPOLL_CTL_MOD
 308 and
 309 .I events
 310 included
 311 .BR EPOLLEXCLUSIVE .
 312 .TP
 313 .B EINVAL
 314 .I op
 315 was
 316 .B EPOLL_CTL_MOD
 317 and the
 318 .B EPOLLEXCLUSIVE
 319 flag has previously been applied to this
 320 .IR epfd ,\~ fd
 321 pair.
 322 .TP
 323 .B EINVAL
 324 .B EPOLLEXCLUSIVE
 325 was specified in
 326 .I event
 327 and
 328 .I fd
 329 refers to an epoll instance.
 330 .TP
 331 .B ELOOP
 332 .I fd
 333 refers to an epoll instance and this
 334 .B EPOLL_CTL_ADD
 335 operation would result in a circular loop of epoll instances
 336 monitoring one another or a nesting depth of epoll instances
 337 greater than 5.
 338 .TP
 339 .B ENOENT
 340 .I op
 341 was
 342 .B EPOLL_CTL_MOD
 343 or
 344 .BR EPOLL_CTL_DEL ,
 345 and
 346 .I fd
 347 is not registered with this epoll instance.
 348 .TP
 349 .B ENOMEM
 350 There was insufficient memory to handle the requested
 351 .I op
 352 control operation.
 353 .TP
 354 .B ENOSPC
 355 The limit imposed by
 356 .I /proc/sys/fs/epoll/max_user_watches
 357 was encountered while trying to register
 358 .RB ( EPOLL_CTL_ADD )
 359 a new file descriptor on an epoll instance.
 360 See
 361 .BR epoll (7)
 362 for further details.
 363 .TP
 364 .B EPERM
 365 The target file
 366 .I fd
 367 does not support
 368 .BR epoll .
 369 This error can occur if
 370 .I fd
 371 refers to, for example, a regular file or a directory.
 372 .SH VERSIONS
 373 .BR epoll_ctl ()
 374 was added to the kernel in version 2.6.
 375 .\" To be precise: kernel 2.5.44.
 376 .\" The interface should be finalized by Linux kernel 2.5.66.
 377 Library support is provided in glibc starting with version 2.3.2.
 378 .SH STANDARDS
 379 .BR epoll_ctl ()
 380 is Linux-specific.
 381 .SH NOTES
 382 The
 383 .B epoll
 384 interface supports all file descriptors that support
 385 .BR poll (2).
 386 .SH BUGS
 387 In kernel versions before 2.6.9, the
 388 .B EPOLL_CTL_DEL
 389 operation required a non-null pointer in
 390 .IR event ,
 391 even though this argument is ignored.
 392 Since Linux 2.6.9,
 393 .I event
 394 can be specified as NULL
 395 when using
 396 .BR EPOLL_CTL_DEL .
 397 Applications that need to be portable to kernels before 2.6.9
 398 should specify a non-null pointer in
 399 .IR event .
 400 .PP
 401 If
 402 .B EPOLLWAKEUP
 403 is specified in
 404 .IR flags ,
 405 but the caller does not have the
 406 .B CAP_BLOCK_SUSPEND
 407 capability, then the
 408 .B EPOLLWAKEUP
 409 flag is
 410 .IR "silently ignored" .
 411 This unfortunate behavior is necessary because no validity
 412 checks were performed on the
 413 .I flags
 414 argument in the original implementation, and the addition of the
 415 .B EPOLLWAKEUP
 416 with a check that caused the call to fail if the caller did not have the
 417 .B CAP_BLOCK_SUSPEND
 418 capability caused a breakage in at least one existing user-space
 419 application that happened to randomly (and uselessly) specify this bit.
 420 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
 421 .\" https://lwn.net/Articles/520198/
 422 A robust application should therefore double check that it has the
 423 .B CAP_BLOCK_SUSPEND
 424 capability if attempting to use the
 425 .B EPOLLWAKEUP
 426 flag.
 427 .SH SEE ALSO
 428 .BR epoll_create (2),
 429 .BR epoll_wait (2),
 430 .BR poll (2),
 431 .BR epoll (7)