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 2015-05-07 "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 urgent data available for
 119 .BR read (2)
 120 operations.
 121 .TP
 122 .B EPOLLERR
 123 Error condition happened on the associated file descriptor.
 124 .BR epoll_wait (2)
 125 will always wait for this event; it is not necessary to set it in
 126 .IR events .
 127 .TP
 128 .B EPOLLHUP
 129 Hang up happened on the associated file descriptor.
 130 .BR epoll_wait (2)
 131 will always wait for this event; it is not necessary to set it in
 132 .IR events .
 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 .SH RETURN VALUE
 190 When successful,
 191 .BR epoll_ctl ()
 192 returns zero.
 193 When an error occurs,
 194 .BR epoll_ctl ()
 195 returns \-1 and
 196 .I errno
 197 is set appropriately.
 198 .SH ERRORS
 199 .TP
 200 .B EBADF
 201 .I epfd
 202 or
 203 .I fd
 204 is not a valid file descriptor.
 205 .TP
 206 .B EEXIST
 207 .I op
 208 was
 209 .BR EPOLL_CTL_ADD ,
 210 and the supplied file descriptor
 211 .I fd
 212 is already registered with this epoll instance.
 213 .TP
 214 .B EINVAL
 215 .I epfd
 216 is not an
 217 .B epoll
 218 file descriptor,
 219 or
 220 .I fd
 221 is the same as
 222 .IR epfd ,
 223 or the requested operation
 224 .I op
 225 is not supported by this interface.
 226 .TP
 227 .B ELOOP
 228 .I fd
 229 refers to an epoll instance and this
 230 .B EPOLL_CTL_ADD
 231 operation would result in a circular loop of epoll instances
 232 monitoring one another.
 233 .TP
 234 .B ENOENT
 235 .I op
 236 was
 237 .B EPOLL_CTL_MOD
 238 or
 239 .BR EPOLL_CTL_DEL ,
 240 and
 241 .I fd
 242 is not registered with this epoll instance.
 243 .TP
 244 .B ENOMEM
 245 There was insufficient memory to handle the requested
 246 .I op
 247 control operation.
 248 .TP
 249 .B ENOSPC
 250 The limit imposed by
 251 .I /proc/sys/fs/epoll/max_user_watches
 252 was encountered while trying to register
 253 .RB ( EPOLL_CTL_ADD )
 254 a new file descriptor on an epoll instance.
 255 See
 256 .BR epoll (7)
 257 for further details.
 258 .TP
 259 .B EPERM
 260 The target file
 261 .I fd
 262 does not support
 263 .BR epoll .
 264 This error can occur if
 265 .I fd
 266 refers to, for example, a regular file or a directory.
 267 .SH VERSIONS
 268 .BR epoll_ctl ()
 269 was added to the kernel in version 2.6.
 270 .\" To be precise: kernel 2.5.44.
 271 .\" The interface should be finalized by Linux kernel 2.5.66.
 272 .SH CONFORMING TO
 273 .BR epoll_ctl ()
 274 is Linux-specific.
 275 Library support is provided in glibc starting with version 2.3.2.
 276 .SH NOTES
 277 The
 278 .B epoll
 279 interface supports all file descriptors that support
 280 .BR poll (2).
 281 .SH BUGS
 282 In kernel versions before 2.6.9, the
 283 .B EPOLL_CTL_DEL
 284 operation required a non-null pointer in
 285 .IR event ,
 286 even though this argument is ignored.
 287 Since Linux 2.6.9,
 288 .I event
 289 can be specified as NULL
 290 when using
 291 .BR EPOLL_CTL_DEL .
 292 Applications that need to be portable to kernels before 2.6.9
 293 should specify a non-null pointer in
 294 .IR event .
 295
 296 If
 297 .B EPOLLWAKEUP
 298 is specified in
 299 .IR flags ,
 300 but the caller does not have the
 301 .BR CAP_BLOCK_SUSPEND
 302 capability, then the
 303 .B EPOLLWAKEUP
 304 flag is
 305 .IR "silently ignored" .
 306 This unfortunate behavior is necessary because no validity
 307 checks were performed on the
 308 .IR flags
 309 argument in the original implementation, and the addition of the
 310 .B EPOLLWAKEUP
 311 with a check that caused the call to fail if the caller did not have the
 312 .B CAP_BLOCK_SUSPEND
 313 capability caused a breakage in at least one existing user-space
 314 application that happened to randomly (and uselessly) specify this bit.
 315 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
 316 .\" https://lwn.net/Articles/520198/
 317 A robust application should therefore double check that it has the
 318 .B CAP_BLOCK_SUSPEND
 319 capability if attempting to use the
 320 .B EPOLLWAKEUP
 321 flag.
 322 .SH SEE ALSO
 323 .BR epoll_create (2),
 324 .BR epoll_wait (2),
 325 .BR poll (2),
 326 .BR epoll (7)