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