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