man2/epoll_ctl.2

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