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