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