Print this page
11641 spelling mistakes in section 7d of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/poll.7d
+++ new/usr/src/man/man7d/poll.7d
1 1 '\" te
2 2 .\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH POLL 7D "April 9, 2016"
6 +.TH POLL 7D "January 10, 2020"
7 7 .SH NAME
8 8 poll \- driver for fast poll on many file descriptors
9 9 .SH SYNOPSIS
10 -.LP
11 10 .nf
12 11 \fB#include <sys/devpoll.h>
13 12 int fd = open("/dev/poll", O_RDWR);
14 13 ssize_t n = write(int fd, struct pollfd buf[], int bufsize);
15 14 int n = ioctl(int fd, DP_POLL, struct dvpoll* arg);
16 15 int n = ioctl(int fd, DP_ISPOLLED, struct pollfd* pfd);\fR
17 16 .fi
18 17
19 18 .SH PARAMETERS
20 19 .ne 2
21 20 .na
22 21 \fB\fIfd\fR \fR
23 22 .ad
24 23 .RS 12n
25 24 Open file descriptor that refers to the \fB/dev/poll\fR driver.
26 25 .RE
27 26
28 27 .sp
29 28 .ne 2
30 29 .na
31 30 \fB\fIpath\fR \fR
32 31 .ad
33 32 .RS 12n
34 33 \fB/dev/poll\fR
35 34 .RE
36 35
37 36 .sp
38 37 .ne 2
39 38 .na
40 39 \fB\fIbuf\fR \fR
41 40 .ad
42 41 .RS 12n
43 42 Array of \fBpollfd\fR structures.
44 43 .RE
45 44
46 45 .sp
47 46 .ne 2
48 47 .na
49 48 \fB\fIbufsize\fR \fR
50 49 .ad
51 50 .RS 12n
52 51 Size of \fIbuf\fR in bytes.
53 52 .RE
54 53
55 54 .sp
56 55 .ne 2
57 56 .na
58 57 \fB\fIarg\fR \fR
59 58 .ad
60 59 .RS 12n
61 60 Pointer to \fBpollcall\fR structure.
62 61 .RE
63 62
|
↓ open down ↓ |
43 lines elided |
↑ open up ↑ |
64 63 .sp
65 64 .ne 2
66 65 .na
67 66 \fB\fIpfd\fR \fR
68 67 .ad
69 68 .RS 12n
70 69 Pointer to \fBpollfd\fR structure.
71 70 .RE
72 71
73 72 .SH DESCRIPTION
74 -.LP
75 73 The \fB/dev/poll\fR driver is a special driver that enables you to monitor
76 74 multiple sets of polled file descriptors. By using the \fB/dev/poll\fR
77 75 driver, you can efficiently poll large numbers of file descriptors. Access to
78 76 the \fB/dev/poll\fR driver is provided through \fBopen\fR(2), \fBwrite\fR(2),
79 77 and \fBioctl(2)\fR system calls.
80 78 .sp
81 79 .LP
82 80 Writing an array of \fBpollfd\fR struct to the \fB/dev/poll\fR driver has the
83 81 effect of adding these file descriptors to the monitored \fBpoll\fR file
84 82 descriptor set represented by the \fIfd\fR. To monitor multiple file
85 83 descriptor sets, open the \fB/dev/poll\fR driver multiple times. Each \fBfd\fR
86 84 corresponds to one set. For each \fBpollfd\fR struct entry (defined in
87 85 \fBsys/poll.h\fR):
88 86 .sp
89 87 .in +2
90 88 .nf
91 89 struct pollfd {
92 90 int fd;
93 91 short events;
94 92 short revents;
95 93 }
96 94 .fi
97 95 .in -2
98 96
99 97 .sp
100 98 .LP
101 99 The \fBfd\fR field specifies the file descriptor being polled. The
102 100 \fBevents\fR field indicates the interested \fBpoll\fR \fBevents\fR on the file
103 101 descriptor. If a \fBpollfd\fR array contains multiple \fBpollfd\fR entries with
104 102 the same \fBfd\fR field, the "events" field in each \fBpollfd\fR entry is
105 103 OR'ed. A special \fBPOLLREMOVE\fR event in the \fBevents\fR field of the
106 104 \fBpollfd\fR structure removes the \fBfd\fR from the monitored set. The
107 105 \fBrevents\fR field is not used. Write returns the number of bytes written
108 106 successfully or \fB-1\fR when write fails.
109 107 .sp
110 108 .LP
111 109 The \fBDP_POLL\fR ioctl is used to retrieve returned \fBpoll\fR \fBevents\fR
112 110 occurred on the polled file descriptors in the monitored set represented by
113 111 \fIfd\fR. \fIarg\fR \fIis\fR \fIa\fR pointer to the devpoll structures which
114 112 are defined as follows:
115 113 .sp
116 114 .in +2
117 115 .nf
118 116 struct dvpoll {
119 117 struct pollfd* dp_fds;
120 118 int dp_nfds;
121 119 int dp_timeout;
122 120 }
123 121 .fi
124 122 .in -2
125 123
126 124 .sp
127 125 .LP
128 126 The \fBdp_fds\fR points to a buffer that holds an array of returned
129 127 \fBpollfd\fR structures. The \fBdp_nfds\fR field specifies the size of the
130 128 buffer in terms of the number of \fBpollfd\fR entries it contains. The
131 129 \fBdp_nfds\fR field also indicates the maximum number of file descriptors from
132 130 which poll information can be obtained. If there is no interested \fBevents\fR
|
↓ open down ↓ |
48 lines elided |
↑ open up ↑ |
133 131 on any of the polled file descriptors, the \fBDP_POLL\fR ioctl call will wait
134 132 \fBdp_timeout\fR milliseconds before returning. If \fBdp_timeout\fR is
135 133 \fB0\fR, the ioctl call returns immediately. If \fBdp_timeout\fR is \fB-1\fR,
136 134 the call blocks until an interested \fBpoll\fR \fBevents\fR is available or the
137 135 call is interrupted. Upon return, if the ioctl call has failed, \fB-1\fR is
138 136 returned. The memory content pointed by \fBdp_fds\fR is not modified. A return
139 137 value \fB0\fR means the ioctl is timed out. In this case, the memory content
140 138 pointed by \fBdp_fds\fR is not modified. If the call is successful, it returns
141 139 the number of valid \fBpollfd\fR entries in the array pointed by \fBdp_fds\fR;
142 140 the contents of the rest of the buffer is undefined. For each valid
143 -\fBpollfd\fR entry, the \fBfd\fR field indicates the file desciptor on which
141 +\fBpollfd\fR entry, the \fBfd\fR field indicates the file descriptor on which
144 142 the polled \fBevents\fR happened. The \fBevents\fR field is the user specified
145 143 \fBpoll\fR \fBevents\fR. The \fBrevents\fR field contains the \fBevents\fR
146 144 occurred. \fB-1\fR is returned if the call fails.
147 145 .sp
148 146 .LP
149 147 \fBDP_ISPOLLED\fR ioctl allows you to query if a file descriptor is already in
150 148 the monitored set represented by \fBfd\fR. The \fBfd\fR field of the
151 149 \fBpollfd\fR structure indicates the file descriptor of interest. The
152 150 \fBDP_ISPOLLED\fR ioctl returns \fB1\fR if the file descriptor is in the set.
153 151 The \fBevents\fR field contains \fB0\fR. The \fBrevents\fR field contains the
154 152 currently polled \fBevents\fR. The ioctl returns \fB0\fR if the file
155 153 descriptor is not in the set. The \fBpollfd\fR structure pointed by \fIpfd\fR
156 154 is not modified. The ioctl returns a \fB-1\fR if the call fails.
157 155 .SH EXAMPLES
158 -.LP
159 156 The following example shows how \fB/dev/poll\fR may be used.
160 157 .sp
161 158 .in +2
162 159 .nf
163 160 {
164 161 ...
165 162 /*
166 163 * open the driver
167 164 */
168 165 if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
169 166 exit(-1);
170 167 }
171 168 pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
172 169 if (pollfd == NULL) {
173 170 close(wfd);
174 171 exit(-1);
175 172 }
176 173 /*
177 174 * initialize buffer
178 175 */
179 176 for (i = 0; i < MAXBUF; i++) {
180 177 pollfd[i].fd = fds[i];
181 178 pollfd[i].events = POLLIN;
182 179 pollfd[i].revents = 0;
183 180 }
184 181 if (write(wfd, &pollfd[0], sizeof(struct pollfd) * MAXBUF) !=
185 182 sizeof(struct pollfd) * MAXBUF) {
186 183 perror("failed to write all pollfds");
187 184 close (wfd);
188 185 free(pollfd);
189 186 exit(-1);
190 187 }
191 188 /*
192 189 * read from the devpoll driver
193 190 */
194 191 dopoll.dp_timeout = -1;
195 192 dopoll.dp_nfds = MAXBUF;
196 193 dopoll.dp_fds = pollfd;
197 194 result = ioctl(wfd, DP_POLL, &dopoll);
198 195 if (result < 0) {
199 196 perror("/dev/poll ioctl DP_POLL failed");
200 197 close (wfd);
201 198 free(pollfd);
202 199 exit(-1);
203 200 }
204 201 for (i = 0; i < result; i++) {
205 202 read(dopoll.dp_fds[i].fd, rbuf, STRLEN);
206 203 }
207 204 ...
208 205 }
209 206 .fi
210 207 .in -2
211 208
212 209 .sp
213 210 .LP
214 211 The following example is part of a test program which shows how
215 212 \fBDP_ISPOLLED()\fR ioctl may be used.
216 213 .sp
217 214 .in +2
218 215 .nf
219 216 {
220 217 ...
221 218
222 219 loopcnt = 0;
223 220 while (loopcnt < ITERATION) {
224 221 rn = random();
225 222 rn %= RANGE;
226 223 if (write(fds[rn], TESTSTRING, strlen(TESTSTRING)) !=
227 224 strlen(TESTSTRING)) {
228 225 perror("write to fifo failed.");
229 226 close (wfd);
230 227 free(pollfd);
231 228 error = 1;
232 229 goto out1;
233 230 }
234 231 dpfd.fd = fds[rn];
235 232 dpfd.events = 0;
236 233 dpfd.revents = 0;
237 234 result = ioctl(wfd, DP_ISPOLLED, &dpfd);
238 235 if (result < 0) {
239 236 perror("/dev/poll ioctl DP_ISPOLLED failed");
240 237 printf("errno = %d\en", errno);
241 238 close (wfd);
242 239 free(pollfd);
243 240 error = 1;
244 241 goto out1;
245 242 }
246 243 if (result != 1) {
247 244 printf("DP_ISPOLLED returned incorrect result: %d.\en",
248 245 result);
249 246 close (wfd);
250 247 free(pollfd);
251 248 error = 1;
252 249 goto out1;
253 250 }
254 251 if (dpfd.fd != fds[rn]) {
255 252 printf("DP_ISPOLLED returned wrong fd %d, expect %d\en",
256 253 dpfd.fd, fds[rn]);
257 254 close (wfd);
258 255 free(pollfd);
259 256 error = 1;
260 257 goto out1;
261 258 }
262 259 if (dpfd.revents != POLLIN) {
263 260 printf("DP_ISPOLLED returned unexpected revents %d\en",
264 261 dpfd.revents);
265 262 close (wfd);
266 263 free(pollfd);
267 264 error = 1;
268 265 goto out1;
269 266 }
270 267 if (read(dpfd.fd, rbuf, strlen(TESTSTRING)) !=
271 268 strlen(TESTSTRING)) {
272 269 perror("read from fifo failed");
273 270 close (wfd);
274 271 free(pollfd);
275 272 error = 1;
276 273 goto out1;
277 274 }
278 275 loopcnt++;
279 276 }
280 277
281 278 .fi
282 279 .in -2
283 280
284 281 .SH ERRORS
285 282 .ne 2
286 283 .na
287 284 \fB\fBEACCES\fR \fR
288 285 .ad
289 286 .RS 11n
290 287 A process does not have permission to access the content cached in
291 288 \fB/dev/poll\fR.
292 289 .RE
293 290
294 291 .sp
295 292 .ne 2
296 293 .na
297 294 \fB\fBEINTR\fR \fR
298 295 .ad
299 296 .RS 11n
300 297 A signal was caught during the execution of the \fBioctl\fR(2) function.
301 298 .RE
302 299
303 300 .sp
304 301 .ne 2
305 302 .na
306 303 \fB\fBEFAULT\fR \fR
307 304 .ad
308 305 .RS 11n
309 306 The request argument requires a data transfer to or from a buffer pointed to by
310 307 \fIarg\fR, but \fIarg\fR points to an illegal address.
311 308 .RE
312 309
313 310 .sp
314 311 .ne 2
315 312 .na
316 313 \fB\fBEINVAL\fR \fR
317 314 .ad
318 315 .RS 11n
319 316 The request or \fIarg\fR parameter is not valid for this device, or field of
320 317 the dvpoll struct pointed by \fIarg\fR is not valid (for example, when using
321 318 write/pwrite dp_nfds is greater than {OPEN_MAX}, or when using the DPPOLL ioctl
322 319 dp_nfds is greater than or equal to {OPEN_MAX}}.
323 320 .RE
324 321
325 322 .sp
326 323 .ne 2
327 324 .na
|
↓ open down ↓ |
159 lines elided |
↑ open up ↑ |
328 325 \fB\fBENXIO\fR \fR
329 326 .ad
330 327 .RS 11n
331 328 The \fBO_NONBLOCK\fR flag is set, the named file is a FIFO, the \fBO_WRONLY\fR
332 329 flag is set, and no process has the file open for reading; or the named file is
333 330 a character special or block special file and the device associated with this
334 331 special file does not exist.
335 332 .RE
336 333
337 334 .SH ATTRIBUTES
338 -.LP
339 335 See \fBattributes\fR(5) for a description of the following attributes:
340 336 .sp
341 337
342 338 .sp
343 339 .TS
344 340 box;
345 341 l l
346 342 l l .
347 343 ATTRIBUTE TYPE ATTRIBUTE VALUE
348 344 Architecture SPARC, x86
349 345 Interface Stability Obsolete
350 346 MT-Level Safe
351 347 .TE
352 348
353 349 .SH SEE ALSO
354 -.LP
355 350 \fBopen\fR(2), \fBpoll\fR(2), \fBwrite\fR(2), \fBattributes\fR(5)
356 351 .SH NOTES
357 -.LP
358 352 The \fB/dev/poll\fR API is particularly beneficial to applications that poll a
359 353 large number of file descriptors repeatedly. Applications will exhibit the
360 354 best performance gain if the polled file descriptor list rarely change.
361 355 .sp
362 356 .LP
363 357 When using the \fB/dev/poll\fR driver, you should remove a closed file
364 358 descriptor from a monitored poll set. Failure to do so may result in a
365 359 \fBPOLLNVAL\fR \fBrevents\fR being returned for the closed file descriptor.
366 360 When a file descriptor is closed but not removed from the monitored set, and is
367 361 reused in subsequent open of a different device, you will be polling the device
368 362 associated with the reused file descriptor. In a multithreaded application,
369 363 careful coordination among threads doing close and \fBDP_POLL\fR ioctl is
370 364 recommended for consistent results.
371 365 .sp
372 366 .LP
373 367 The \fB/dev/poll\fR driver caches a list of polled file descriptors, which are
374 368 specific to a process. Therefore, the \fB/dev/poll\fR file descriptor of a
375 369 process will be inherited by its child process, just like any other file
376 370 descriptors. But the child process will have very limited access through this
377 371 inherited \fB/dev/poll\fR file descriptor. Any attempt to write or do ioctl by
378 372 the child process will result in an \fBEACCES\fR error. The child process
379 373 should close the inherited \fB/dev/poll\fR file descriptor and open its own if
380 374 desired.
381 375 .sp
382 376 .LP
383 377 The \fB/dev/poll\fR driver does not yet support polling. Polling on a
384 378 \fB/dev/poll\fR file descriptor will result in \fBPOLLERR\fR being returned in
385 379 the \fBrevents\fR field of \fBpollfd\fR structure.
|
↓ open down ↓ |
18 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX