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