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