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