man2/epoll_ctl.2

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