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)