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