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