man2/epoll_ctl.2

   1 .\"  epoll by Davide Libenzi ( efficient event notification retrieval )
   2 .\"  Copyright (C) 2003  Davide Libenzi
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_3_PARA_SW)
   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 .\" %%%END_LICENSE
  19 .\"
  20 .\"  Davide Libenzi <davidel@xmailserver.org>
  21 .\"
  22 .TH EPOLL_CTL 2 2012-04-15 "Linux" "Linux Programmer's Manual"
  23 .SH NAME
  24 epoll_ctl \- control interface for an epoll descriptor
  25 .SH SYNOPSIS
  26 .B #include <sys/epoll.h>
  27 .sp
  28 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
  29 ", struct epoll_event *" event );
  30 .SH DESCRIPTION
  31 This system call performs control operations on the
  32 .BR epoll (7)
  33 instance
  34 referred to by the file descriptor
  35 .IR epfd .
  36 It requests that the operation
  37 .I op
  38 be performed for the target file descriptor,
  39 .IR fd .
  40
  41 Valid values for the
  42 .I op
  43 argument are :
  44 .TP
  45 .B EPOLL_CTL_ADD
  46 Register the target file descriptor
  47 .I fd
  48 on the
  49 .B epoll
  50 instance referred to by the file descriptor
  51 .I epfd
  52 and associate the event
  53 .I event
  54 with the internal file linked to
  55 .IR fd .
  56 .TP
  57 .B EPOLL_CTL_MOD
  58 Change the event
  59 .I event
  60 associated with the target file descriptor
  61 .IR fd .
  62 .TP
  63 .B EPOLL_CTL_DEL
  64 Remove (deregister) the target file descriptor
  65 .I fd
  66 from the
  67 .B epoll
  68 instance referred to by
  69 .IR epfd .
  70 The
  71 .I event
  72 is ignored and can be NULL (but see BUGS below).
  73 .PP
  74 The
  75 .I event
  76 argument describes the object linked to the file descriptor
  77 .IR fd .
  78 The
  79 .I struct epoll_event
  80 is defined as :
  81 .sp
  82 .in +4n
  83 .nf
  84 typedef union epoll_data {
  85     void        *ptr;
  86     int          fd;
  87     uint32_t     u32;
  88     uint64_t     u64;
  89 } epoll_data_t;
  90
  91 struct epoll_event {
  92     uint32_t     events;      /* Epoll events */
  93     epoll_data_t data;        /* User data variable */
  94 };
  95 .fi
  96 .in
  97
  98 The
  99 .I events
 100 member is a bit set composed using the following available event
 101 types:
 102 .TP
 103 .B EPOLLIN
 104 The associated file is available for
 105 .BR read (2)
 106 operations.
 107 .TP
 108 .B EPOLLOUT
 109 The associated file is available for
 110 .BR write (2)
 111 operations.
 112 .TP
 113 .BR EPOLLRDHUP " (since Linux 2.6.17)"
 114 Stream socket peer closed connection,
 115 or shut down writing half of connection.
 116 (This flag is especially useful for writing simple code to detect
 117 peer shutdown when using Edge Triggered monitoring.)
 118 .TP
 119 .B EPOLLPRI
 120 There is urgent data available for
 121 .BR read (2)
 122 operations.
 123 .TP
 124 .B EPOLLERR
 125 Error condition happened on the associated file descriptor.
 126 .BR epoll_wait (2)
 127 will always wait for this event; it is not necessary to set it in
 128 .IR events .
 129 .TP
 130 .B EPOLLHUP
 131 Hang up happened on the associated file descriptor.
 132 .BR epoll_wait (2)
 133 will always wait for this event; it is not necessary to set it in
 134 .IR events .
 135 .TP
 136 .B EPOLLET
 137 Sets the Edge Triggered behavior for the associated file descriptor.
 138 The default behavior for
 139 .B epoll
 140 is Level Triggered.
 141 See
 142 .BR epoll (7)
 143 for more detailed information about Edge and Level Triggered event
 144 distribution architectures.
 145 .TP
 146 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 147 Sets the one-shot behavior for the associated file descriptor.
 148 This means that after an event is pulled out with
 149 .BR epoll_wait (2)
 150 the associated file descriptor is internally disabled and no other events
 151 will be reported by the
 152 .B epoll
 153 interface.
 154 The user must call
 155 .BR epoll_ctl ()
 156 with
 157 .B EPOLL_CTL_MOD
 158 to rearm the file descriptor with a new event mask.
 159 .SH RETURN VALUE
 160 When successful,
 161 .BR epoll_ctl ()
 162 returns zero.
 163 When an error occurs,
 164 .BR epoll_ctl ()
 165 returns \-1 and
 166 .I errno
 167 is set appropriately.
 168 .SH ERRORS
 169 .TP
 170 .B EBADF
 171 .I epfd
 172 or
 173 .I fd
 174 is not a valid file descriptor.
 175 .TP
 176 .B EEXIST
 177 .I op
 178 was
 179 .BR EPOLL_CTL_ADD ,
 180 and the supplied file descriptor
 181 .I fd
 182 is already registered with this epoll instance.
 183 .TP
 184 .B EINVAL
 185 .I epfd
 186 is not an
 187 .B epoll
 188 file descriptor,
 189 or
 190 .I fd
 191 is the same as
 192 .IR epfd ,
 193 or the requested operation
 194 .I op
 195 is not supported by this interface.
 196 .TP
 197 .B ENOENT
 198 .I op
 199 was
 200 .B EPOLL_CTL_MOD
 201 or
 202 .BR EPOLL_CTL_DEL ,
 203 and
 204 .I fd
 205 is not registered with this epoll instance.
 206 .TP
 207 .B ENOMEM
 208 There was insufficient memory to handle the requested
 209 .I op
 210 control operation.
 211 .TP
 212 .B ENOSPC
 213 The limit imposed by
 214 .I /proc/sys/fs/epoll/max_user_watches
 215 was encountered while trying to register
 216 .RB ( EPOLL_CTL_ADD )
 217 a new file descriptor on an epoll instance.
 218 See
 219 .BR epoll (7)
 220 for further details.
 221 .TP
 222 .B EPERM
 223 The target file
 224 .I fd
 225 does not support
 226 .BR epoll .
 227 .SH VERSIONS
 228 .BR epoll_ctl ()
 229 was added to the kernel in version 2.6.
 230 .\" To be precise: kernel 2.5.44.
 231 .\" The interface should be finalized by Linux kernel 2.5.66.
 232 .SH CONFORMING TO
 233 .BR epoll_ctl ()
 234 is Linux-specific.
 235 Library support is provided in glibc starting with version 2.3.2.
 236 .SH NOTES
 237 The
 238 .B epoll
 239 interface supports all file descriptors that support
 240 .BR poll (2).
 241 .SH BUGS
 242 In kernel versions before 2.6.9, the
 243 .B EPOLL_CTL_DEL
 244 operation required a non-NULL pointer in
 245 .IR event ,
 246 even though this argument is ignored.
 247 Since Linux 2.6.9,
 248 .I event
 249 can be specified as NULL
 250 when using
 251 .BR EPOLL_CTL_DEL .
 252 Applications that need to be portable to kernels before 2.6.9
 253 should specify a non-NULL pointer in
 254 .IR event .
 255 .SH SEE ALSO
 256 .BR epoll_create (2),
 257 .BR epoll_wait (2),
 258 .BR poll (2),
 259 .BR epoll (7)