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