Print this page
11641 spelling mistakes in section 7d of the manual
   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


  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;


 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          */


 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
   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


  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;


 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          */


 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