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 "Sep 10, 2013"
   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\en", 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.\en",
 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\en",
 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\en",
 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.