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