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