usr/src/man/man3c/epoll_ctl.3c

   1 '\" te
   2 .\"  Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
   3 .\"  This file and its contents are supplied under the terms of the
   4 .\"  Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\"  You may only use this file in accordance with the terms of version
   6 .\"  1.0 of the CDDL.
   7 .\"
   8 .\"  A full copy of the text of the CDDL should have accompanied this
   9 .\"  source.  A copy of the CDDL is also available via the Internet at
  10 .\"  http://www.illumos.org/license/CDDL.
  11 .TH EPOLL_CTL 3C "April 9, 2016"
  12 .SH NAME
  13 epoll_ctl \- control an epoll instance
  14 .SH SYNOPSIS
  15
  16 .LP
  17 .nf
  18 #include <sys/epoll.h>
  19
  20 \fBint\fR \fBepoll_ctl\fR(\fBint\fR \fIepfd\fR, \fBint\fR \fIop\fR, \fBint\fR \fIfd\fR, \fBstruct epoll_event *\fR\fIevent\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .LP
  25 The \fBepoll_ctl()\fR function executes the operation specified by
  26 \fIop\fR (as parameterized by \fIevent\fR) on the \fIepfd\fR epoll instance.
  27 Valid values for \fIop\fR:
  28
  29 .sp
  30 .ne 2
  31 .na
  32 \fBEPOLL_CTL_ADD\fR
  33 .ad
  34 .RS 12n
  35 For the \fBepoll\fR(5) instance specified by \fIepfd\fR,
  36 associate the file descriptor specified by \fIfd\fR with the event specified
  37 by \fIevent\fR.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fBEPOLL_CTL_DEL\fR
  44 .ad
  45 .RS 12n
  46 For the \fBepoll\fR(5) instance specified by \fIepfd\fR,
  47 remove all event associations for the file descriptor specified by \fIfd\fR.
  48 \fIevent\fR is ignored, and may be NULL.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fBEPOLL_CTL_MOD\fR
  55 .ad
  56 .RS 12n
  57 For the \fBepoll\fR(5) instance specified by \fIepfd\fR, modify the event
  58 association for the file descriptor specified by \fIfd\fR to be that
  59 specified by \fIevent\fR.
  60
  61 .RE
  62
  63 The \fIevent\fR parameter has the following structure:
  64
  65 .in +4
  66 .nf
  67 typedef union epoll_data {
  68         void    *ptr;
  69         int      fd;
  70         uint32_t u32;
  71         uint64_t u64;
  72 } epoll_data_t;
  73
  74 struct epoll_event {
  75         uint32_t     events;
  76         epoll_data_t data;
  77 };
  78 .fi
  79 .in -4
  80
  81 The \fIdata\fR field specifies the datum to
  82 be associated with the event and
  83 will be returned via \fBepoll_wait\fR(3C).
  84 The \fIevents\fR field denotes both the desired events (when specified via
  85 \fBepoll_ctl()\fR) and the events that have occurred (when returned via
  86 \fBepoll_wait\fR(3C)).
  87 In either case, the
  88 \fIevents\fR field is a bitmask constructed by a logical \fBOR\fR operation
  89 of any combination of the following event flags:
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fBEPOLLIN\fR
  95 .ad
  96 .RS 14n
  97 Data other than high priority data may be read without blocking. For streams,
  98 this flag is set in the returned \fIevents\fR even if the message is of
  99 zero length.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fBEPOLLPRI\fR
 106 .ad
 107 .RS 14n
 108 Normal data (priority band equals 0) may be read without blocking. For streams,
 109 this flag is set in the returned \fIevents\fR even if the message is of zero
 110 length.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fBEPOLLOUT\fR
 117 .ad
 118 .RS 14n
 119 Normal data (priority band equals 0) may be written without blocking.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fBEPOLLRDNORM\fR
 126 .ad
 127 .RS 14n
 128 Normal data (priority band equals 0) may be read without blocking. For streams,
 129 this flag is set in the returned \fIrevents\fR even if the message is of
 130 zero length.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fBEPOLLRDBAND\fR
 137 .ad
 138 .RS 14n
 139 Data from a non-zero priority band may be read without blocking. For streams,
 140 this flag is set in the returned \fIrevents\fR even if the message is of
 141 zero length.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fBEPOLLWRNORM\fR
 148 .ad
 149 .RS 14n
 150 The same as \fBEPOLLOUT\fR.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fBEPOLLWRBAND\fR
 157 .ad
 158 .RS 14n
 159 Priority data (priority band > 0) may be written.  This event only examines
 160 bands that have been written to at least once.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fBEPOLLMSG\fR
 167 .ad
 168 .RS 14n
 169 This exists only for backwards binary and source compatibility with Linux;
 170 it has no meaning and is ignored.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fBEPOLLERR\fR
 177 .ad
 178 .RS 14n
 179 An error has occurred on the device or stream.  This flag is only valid in the
 180 returned \fIevents\fR field.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fBEPOLLHUP\fR
 187 .ad
 188 .RS 14n
 189 A hangup has occurred on the stream. This event and \fBEPOLLOUT\fR are mutually
 190 exclusive; a stream can never be writable if a hangup has occurred. However,
 191 this event and  \fBEPOLLIN\fR, \fBEPOLLRDNORM\fR, \fBEPOLLRDBAND\fR,
 192 \fBEPOLLRDHUP\fR or
 193 \fBEPOLLPRI\fR are not mutually exclusive. This flag is only valid in the
 194 \fIevents\fR field returned from \fBepoll_wait\fR(3C); it is not used in the
 195 \fIevents\fR field specified via \fBepoll_ctl()\fR.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fBEPOLLRDHUP\fR
 202 .ad
 203 .RS 14n
 204 The stream socket peer shutdown the writing half of the connection and no
 205 further data will be readable via the socket.  This event is not mutually
 206 exclusive with \fBEPOLLIN\fR.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fBEPOLLWAKEUP\fR
 213 .ad
 214 .RS 14n
 215 This exists only for backwards binary and source compatibility with Linux;
 216 it has no meaning and is ignored.
 217 .RE
 218
 219 .sp
 220 .ne 2
 221 .na
 222 \fBEPOLLONESHOT\fR
 223 .ad
 224 .RS 14n
 225 Sets the specified event to be in one-shot mode, whereby the event association
 226 with the \fBepoll\fR(5) instance specified by \fIepfd\fR is removed atomically
 227 as the event is returned via \fBepoll_wait\fR(3C).  Use of this mode allows
 228 for resolution of some of the
 229 races inherent in multithreaded use of \fBepoll_wait\fR(3C).
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fBEPOLLET\fR
 236 .ad
 237 .RS 14n
 238 Sets the specified event to be edge-triggered mode instead of the default
 239 mode of level-triggered.  In this mode, events will be induced by
 240 transitions on an event source rather than the state of the event source.
 241 While perhaps superficially appealing, this mode introduces several new
 242 potential failure modes for user-level software and should be used
 243 with caution.
 244 .RE
 245
 246 .SH RETURN VALUES
 247 .LP
 248 Upon successful completion, \fBepoll_ctl()\fR returns 0.
 249 If an error occurs, -1 is returned and errno is set to indicate
 250 the error.
 251
 252 .SH ERRORS
 253 .LP
 254 \fBepoll_ctl()\fR will fail if:
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBEBADF\fR\fR
 259 .ad
 260 .RS 10n
 261 \fIepfd\fR is not a valid file descriptor.
 262 .RE
 263
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fBEFAULT\fR\fR
 268 .ad
 269 .RS 10n
 270 The memory associated with \fIevent\fR was not mapped.
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fBEEXIST\fR\fR
 277 .ad
 278 .RS 10n
 279 The operation specified was \fBEPOLL_CTL_ADD\fR and the specified file
 280 descriptor is already associated with an event for the specified
 281 \fBepoll\fR(5) instance.
 282 .RE
 283
 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fBENOENT\fR\fR
 288 .ad
 289 .RS 10n
 290 The operation specified was \fBEPOLL_CTL_MOD\fR or \fBEPOLL_CTL_DEL\fR and
 291 the specified file descriptor is not associated with an event for the
 292 specified \fBepoll\fR(5) instance.
 293 .RE
 294
 295 .sp
 296 .SH NOTES
 297 .LP
 298
 299 The \fBepoll\fR(5) facility is implemented for purposes of offering
 300 compatibility for Linux-borne applications; native
 301 applications should continue to prefer using event ports via the
 302 \fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C)
 303 interfaces.  See \fBepoll\fR(5) for compatibility details and restrictions.
 304
 305 .SH SEE ALSO
 306 .LP
 307 \fBepoll_create\fR(3C), \fBepoll_wait\fR(3C),
 308 \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C),
 309 \fBepoll\fR(5)