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 2016-10-08 "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 using the following available event
  99 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 Note that when reading from a channel such as a pipe or a stream socket,
 138 this event merely indicates that the peer closed its end of the channel.
 139 Subsequent reads from the channel will return 0 (end of file)
 140 only after all outstanding data in the channel has been consumed.
 141 .TP
 142 .B EPOLLET
 143 Sets the Edge Triggered behavior for the associated file descriptor.
 144 The default behavior for
 145 .B epoll
 146 is Level Triggered.
 147 See
 148 .BR epoll (7)
 149 for more detailed information about Edge and Level Triggered event
 150 distribution architectures.
 151 .TP
 152 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 153 Sets the one-shot behavior for the associated file descriptor.
 154 This means that after an event is pulled out with
 155 .BR epoll_wait (2)
 156 the associated file descriptor is internally disabled and no other events
 157 will be reported by the
 158 .B epoll
 159 interface.
 160 The user must call
 161 .BR epoll_ctl ()
 162 with
 163 .B EPOLL_CTL_MOD
 164 to rearm the file descriptor with a new event mask.
 165 .TP
 166 .BR EPOLLWAKEUP " (since Linux 3.5)"
 167 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
 168 If
 169 .B EPOLLONESHOT
 170 and
 171 .B EPOLLET
 172 are clear and the process has the
 173 .B CAP_BLOCK_SUSPEND
 174 capability,
 175 ensure that the system does not enter "suspend" or
 176 "hibernate" while this event is pending or being processed.
 177 The event is considered as being "processed" from the time
 178 when it is returned by a call to
 179 .BR epoll_wait (2)
 180 until the next call to
 181 .BR epoll_wait (2)
 182 on the same
 183 .BR epoll (7)
 184 file descriptor,
 185 the closure of that file descriptor,
 186 the removal of the event file descriptor with
 187 .BR EPOLL_CTL_DEL ,
 188 or the clearing of
 189 .B EPOLLWAKEUP
 190 for the event file descriptor with
 191 .BR EPOLL_CTL_MOD .
 192 See also BUGS.
 193 .TP
 194 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
 195 Sets an exclusive wakeup mode for the epoll file descriptor that is being
 196 attached to the target file descriptor,
 197 .IR fd .
 198 When a wakeup event occurs and multiple epoll file descriptors
 199 are attached to the same target file using
 200 .BR EPOLLEXCLUSIVE ,
 201 one or more of the epoll file descriptors will receive an event with
 202 .BR epoll_wait (2).
 203 The default in this scenario (when
 204 .BR EPOLLEXCLUSIVE
 205 is not set) is for all epoll file descriptors to receive an event.
 206 .BR EPOLLEXCLUSIVE
 207 is thus useful for avoiding thundering herd problems in certain scenarios.
 208
 209 If the same file descriptor is in multiple epoll instances,
 210 some with the
 211 .BR EPOLLEXCLUSIVE
 212 flag, and others without, then events will be provided to all epoll
 213 instances that did not specify
 214 .BR EPOLLEXCLUSIVE ,
 215 and at least one of the epoll instances that did specify
 216 .BR EPOLLEXCLUSIVE .
 217
 218 The following values may be specified in conjunction with
 219 .BR EPOLLEXCLUSIVE :
 220 .BR EPOLLIN ,
 221 .BR EPOLLOUT ,
 222 .BR EPOLLWAKEUP,
 223 and
 224 .BR EPOLLET .
 225 .BR EPOLLHUP
 226 and
 227 .BR EPOLLERR
 228 can also be specified, but this is not required:
 229 as usual, these events are always reported if they occur,
 230 regardless of whether they are specified in
 231 .IR events .
 232 Attempts to specify other values in
 233 .I events
 234 yield an error.
 235 .B EPOLLEXCLUSIVE
 236 may be used only in an
 237 .B EPOLL_CTL_ADD
 238 operation; attempts to employ it with
 239 .B EPOLL_CTL_MOD
 240 yield an error.
 241 If
 242 .B EPOLLEXCLUSIVE
 243 has been set using
 244 .BR epoll_ctl (),
 245 then a subsequent
 246 .B EPOLL_CTL_MOD
 247 on the same
 248 .IR epfd ",\ " fd
 249 pair yields an error.
 250 A call to
 251 .BR epoll_ctl ()
 252 that specifies
 253 .B EPOLLEXCLUSIVE
 254 in
 255 .I events
 256 and specifies the target file descriptor
 257 .I fd
 258 as an epoll instance will likewise fail.
 259 The error in all of these cases is
 260 .BR EINVAL .
 261 .SH RETURN VALUE
 262 When successful,
 263 .BR epoll_ctl ()
 264 returns zero.
 265 When an error occurs,
 266 .BR epoll_ctl ()
 267 returns \-1 and
 268 .I errno
 269 is set appropriately.
 270 .SH ERRORS
 271 .TP
 272 .B EBADF
 273 .I epfd
 274 or
 275 .I fd
 276 is not a valid file descriptor.
 277 .TP
 278 .B EEXIST
 279 .I op
 280 was
 281 .BR EPOLL_CTL_ADD ,
 282 and the supplied file descriptor
 283 .I fd
 284 is already registered with this epoll instance.
 285 .TP
 286 .B EINVAL
 287 .I epfd
 288 is not an
 289 .B epoll
 290 file descriptor,
 291 or
 292 .I fd
 293 is the same as
 294 .IR epfd ,
 295 or the requested operation
 296 .I op
 297 is not supported by this interface.
 298 .TP
 299 .B EINVAL
 300 An invalid event type was specified along with
 301 .B EPOLLEXCLUSIVE
 302 in
 303 .IR events .
 304 .TP
 305 .B EINVAL
 306 .I op
 307 was
 308 .B EPOLL_CTL_MOD
 309 and
 310 .IR events
 311 included
 312 .BR EPOLLEXCLUSIVE .
 313 .TP
 314 .B EINVAL
 315 .I op
 316 was
 317 .B EPOLL_CTL_MOD
 318 and the
 319 .BR EPOLLEXCLUSIVE
 320 flag has previously been applied to this
 321 .IR epfd ",\ " fd
 322 pair.
 323 .TP
 324 .B EINVAL
 325 .BR EPOLLEXCLUSIVE
 326 was specified in
 327 .IR event
 328 and
 329 .I fd
 330 refers to an epoll instance.
 331 .TP
 332 .B ELOOP
 333 .I fd
 334 refers to an epoll instance and this
 335 .B EPOLL_CTL_ADD
 336 operation would result in a circular loop of epoll instances
 337 monitoring one another.
 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 .SH CONFORMING TO
 378 .BR epoll_ctl ()
 379 is Linux-specific.
 380 Library support is provided in glibc starting with version 2.3.2.
 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
 401 If
 402 .B EPOLLWAKEUP
 403 is specified in
 404 .IR flags ,
 405 but the caller does not have the
 406 .BR 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 .IR 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)