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