original/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 2012-04-15 "Linux" "Linux Programmer's Manual"
  21 .SH NAME
  22 epoll_ctl \- control interface for an epoll 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 set 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 .TP
 134 .B EPOLLET
 135 Sets the Edge Triggered behavior for the associated file descriptor.
 136 The default behavior for
 137 .B epoll
 138 is Level Triggered.
 139 See
 140 .BR epoll (7)
 141 for more detailed information about Edge and Level Triggered event
 142 distribution architectures.
 143 .TP
 144 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 145 Sets the one-shot behavior for the associated file descriptor.
 146 This means that after an event is pulled out with
 147 .BR epoll_wait (2)
 148 the associated file descriptor is internally disabled and no other events
 149 will be reported by the
 150 .B epoll
 151 interface.
 152 The user must call
 153 .BR epoll_ctl ()
 154 with
 155 .B EPOLL_CTL_MOD
 156 to rearm the file descriptor with a new event mask.
 157 .SH RETURN VALUE
 158 When successful,
 159 .BR epoll_ctl ()
 160 returns zero.
 161 When an error occurs,
 162 .BR epoll_ctl ()
 163 returns \-1 and
 164 .I errno
 165 is set appropriately.
 166 .SH ERRORS
 167 .TP
 168 .B EBADF
 169 .I epfd
 170 or
 171 .I fd
 172 is not a valid file descriptor.
 173 .TP
 174 .B EEXIST
 175 .I op
 176 was
 177 .BR EPOLL_CTL_ADD ,
 178 and the supplied file descriptor
 179 .I fd
 180 is already registered with this epoll instance.
 181 .TP
 182 .B EINVAL
 183 .I epfd
 184 is not an
 185 .B epoll
 186 file descriptor,
 187 or
 188 .I fd
 189 is the same as
 190 .IR epfd ,
 191 or the requested operation
 192 .I op
 193 is not supported by this interface.
 194 .TP
 195 .B ENOENT
 196 .I op
 197 was
 198 .B EPOLL_CTL_MOD
 199 or
 200 .BR EPOLL_CTL_DEL ,
 201 and
 202 .I fd
 203 is not registered with this epoll instance.
 204 .TP
 205 .B ENOMEM
 206 There was insufficient memory to handle the requested
 207 .I op
 208 control operation.
 209 .TP
 210 .B ENOSPC
 211 The limit imposed by
 212 .I /proc/sys/fs/epoll/max_user_watches
 213 was encountered while trying to register
 214 .RB ( EPOLL_CTL_ADD )
 215 a new file descriptor on an epoll instance.
 216 See
 217 .BR epoll (7)
 218 for further details.
 219 .TP
 220 .B EPERM
 221 The target file
 222 .I fd
 223 does not support
 224 .BR epoll .
 225 .SH VERSIONS
 226 .BR epoll_ctl ()
 227 was added to the kernel in version 2.6.
 228 .\" To be precise: kernel 2.5.44.
 229 .\" The interface should be finalized by Linux kernel 2.5.66.
 230 .SH CONFORMING TO
 231 .BR epoll_ctl ()
 232 is Linux-specific.
 233 Library support is provided in glibc starting with version 2.3.2.
 234 .SH NOTES
 235 The
 236 .B epoll
 237 interface supports all file descriptors that support
 238 .BR poll (2).
 239 .SH BUGS
 240 In kernel versions before 2.6.9, the
 241 .B EPOLL_CTL_DEL
 242 operation required a non-null pointer in
 243 .IR event ,
 244 even though this argument is ignored.
 245 Since Linux 2.6.9,
 246 .I event
 247 can be specified as NULL
 248 when using
 249 .BR EPOLL_CTL_DEL .
 250 Applications that need to be portable to kernels before 2.6.9
 251 should specify a non-null pointer in
 252 .IR event .
 253 .SH SEE ALSO
 254 .BR epoll_create (2),
 255 .BR epoll_wait (2),
 256 .BR poll (2),
 257 .BR epoll (7)
 258 .SH COLOPHON
 259 This page is part of release 3.67 of the Linux
 260 .I man-pages
 261 project.
 262 A description of the project,
 263 information about reporting bugs,
 264 and the latest version of this page,
 265 can be found at
 266 \%http://www.kernel.org/doc/man\-pages/.