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