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