man3p/poll.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "POLL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" poll
   4 .SH NAME
   5 poll \- input/output multiplexing
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <poll.h>
   9 .br
  10 .sp
  11 int poll(struct pollfd\fP \fIfds\fP\fB[], nfds_t\fP \fInfds\fP\fB,
  12 int\fP \fItimeout\fP\fB); \fP
  13 \fB
  14 .br
  15 \fP
  16 .SH DESCRIPTION
  17 .LP
  18 The \fIpoll\fP() function provides applications with a mechanism for
  19 multiplexing input/output over a set of file descriptors.
  20 For each member of the array pointed to by \fIfds\fP, \fIpoll\fP()
  21 shall examine the given file descriptor for the event(s)
  22 specified in \fIevents\fP. The number of \fBpollfd\fP structures in
  23 the \fIfds\fP array is specified by \fInfds\fP. The
  24 \fIpoll\fP() function shall identify those file descriptors on which
  25 an application can read or write data, or on which certain
  26 events have occurred.
  27 .LP
  28 The \fIfds\fP argument specifies the file descriptors to be examined
  29 and the events of interest for each file descriptor. It is
  30 a pointer to an array with one member for each open file descriptor
  31 of interest. The array's members are \fBpollfd\fP structures
  32 within which \fIfd\fP specifies an open file descriptor and \fIevents\fP
  33 and \fIrevents\fP are bitmasks constructed by OR'ing a
  34 combination of the following event flags:
  35 .TP 7
  36 POLLIN
  37 Data other than high-priority data may be read without blocking.
  38 .LP
  39 For STREAMS, this flag is set in \fIrevents\fP even if the message
  40 is of zero length. This flag shall be equivalent to POLLRDNORM
  41 | POLLRDBAND.
  42 .TP 7
  43 POLLRDNORM
  44 Normal data may be read without blocking.
  45 .LP
  46 For STREAMS, data on priority band 0 may be read without blocking.
  47 This flag is set in \fIrevents\fP even if the message is of
  48 zero length.
  49 .TP 7
  50 POLLRDBAND
  51 Priority data may be read without blocking.
  52 .LP
  53 For STREAMS, data on priority bands greater than 0 may be read without
  54 blocking. This flag is set in \fIrevents\fP even if the
  55 message is of zero length.
  56 .TP 7
  57 POLLPRI
  58 High-priority data may be read without blocking.
  59 .LP
  60 For STREAMS, this flag is set in \fIrevents\fP even if the message
  61 is of zero length.
  62 .TP 7
  63 POLLOUT
  64 Normal data may be written without blocking.
  65 .LP
  66 For STREAMS, data on priority band 0 may be written without blocking.
  67 .TP 7
  68 POLLWRNORM
  69 Equivalent to POLLOUT.
  70 .TP 7
  71 POLLWRBAND
  72 Priority data may be written.
  73 .LP
  74 For STREAMS, data on priority bands greater than 0 may be written
  75 without blocking. If any priority band has been written to on
  76 this STREAM, this event only examines bands that have been written
  77 to at least once.
  78 .TP 7
  79 POLLERR
  80 An error has occurred on the device or stream. This flag is only valid
  81 in the \fIrevents\fP bitmask; it shall be ignored in
  82 the \fIevents\fP member.
  83 .TP 7
  84 POLLHUP
  85 The device has been disconnected. This event and POLLOUT are mutually-exclusive;
  86 a stream can never be writable if a hangup has
  87 occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND,
  88 or POLLPRI are not mutually-exclusive. This flag is only valid in
  89 the \fIrevents\fP bitmask; it shall be ignored in the \fIevents\fP
  90 member.
  91 .TP 7
  92 POLLNVAL
  93 The specified \fIfd\fP value is invalid. This flag is only valid in
  94 the \fIrevents\fP member; it shall ignored in the
  95 \fIevents\fP member.
  96 .sp
  97 .LP
  98 The significance and semantics of normal, priority, and high-priority
  99 data are file and device-specific.
 100 .LP
 101 If the value of \fIfd\fP is less than 0, \fIevents\fP shall be ignored,
 102 and \fIrevents\fP shall be set to 0 in that entry on
 103 return from \fIpoll\fP().
 104 .LP
 105 In each \fBpollfd\fP structure, \fIpoll\fP() shall clear the \fIrevents\fP
 106 member, except that where the application
 107 requested a report on a condition by setting one of the bits of \fIevents\fP
 108 listed above, \fIpoll\fP() shall set the
 109 corresponding bit in \fIrevents\fP if the requested condition is true.
 110 In addition, \fIpoll\fP() shall set the POLLHUP, POLLERR,
 111 and POLLNVAL flag in \fIrevents\fP if the condition is true, even
 112 if the application did not set the corresponding bit in
 113 \fIevents\fP.
 114 .LP
 115 If none of the defined events have occurred on any selected file descriptor,
 116 \fIpoll\fP() shall wait at least \fItimeout\fP
 117 milliseconds for an event to occur on any of the selected file descriptors.
 118 If the value of \fItimeout\fP is 0, \fIpoll\fP()
 119 shall return immediately. If the value of \fItimeout\fP is -1, \fIpoll\fP()
 120 shall block until a requested event occurs or until
 121 the call is interrupted.
 122 .LP
 123 Implementations may place limitations on the granularity of timeout
 124 intervals. If the requested timeout interval requires a
 125 finer granularity than the implementation supports, the actual timeout
 126 interval shall be rounded up to the next supported
 127 value.
 128 .LP
 129 The \fIpoll\fP() function shall not be affected by the O_NONBLOCK
 130 flag.
 131 .LP
 132 The \fIpoll\fP() function shall support regular files, terminal and
 133 pseudo-terminal devices, FIFOs, pipes, sockets and
 134 \ STREAMS-based files.  The behavior of \fIpoll\fP() on
 135 elements of \fIfds\fP that refer to other types of file is unspecified.
 136 .LP
 137 Regular files shall always poll TRUE for reading and writing.
 138 .LP
 139 A file descriptor for a socket that is listening for connections shall
 140 indicate that it is ready for reading, once connections
 141 are available. A file descriptor for a socket that is connecting asynchronously
 142 shall indicate that it is ready for writing, once a
 143 connection has been established.
 144 .SH RETURN VALUE
 145 .LP
 146 Upon successful completion, \fIpoll\fP() shall return a non-negative
 147 value. A positive value indicates the total number of file
 148 descriptors that have been selected (that is, file descriptors for
 149 which the \fIrevents\fP member is non-zero). A value of 0
 150 indicates that the call timed out and no file descriptors have been
 151 selected. Upon failure, \fIpoll\fP() shall return -1 and set
 152 \fIerrno\fP to indicate the error.
 153 .SH ERRORS
 154 .LP
 155 The \fIpoll\fP() function shall fail if:
 156 .TP 7
 157 .B EAGAIN
 158 The allocation of internal data structures failed but a subsequent
 159 request may succeed.
 160 .TP 7
 161 .B EINTR
 162 A signal was caught during \fIpoll\fP().
 163 .TP 7
 164 .B EINVAL
 165 The \fInfds\fP argument is greater than {OPEN_MAX},   \ or one of
 166 the \fIfd\fP members refers to a STREAM or multiplexer
 167 that is linked (directly or indirectly) downstream from a multiplexer.
 168 .sp
 169 .LP
 170 \fIThe following sections are informative.\fP
 171 .SH EXAMPLES
 172 .SS Checking for Events on a Stream
 173 .LP
 174 The following example opens a pair of STREAMS devices and then waits
 175 for either one to become writable. This example proceeds as
 176 follows:
 177 .IP " 1." 4
 178 Sets the \fItimeout\fP parameter to 500 milliseconds.
 179 .LP
 180 .IP " 2." 4
 181 Opens the STREAMS devices \fB/dev/dev0\fP and \fB/dev/dev1\fP, and
 182 then polls them, specifying POLLOUT and POLLWRBAND as the
 183 events of interest.
 184 .LP
 185 The STREAMS device names \fB/dev/dev0\fP and \fB/dev/dev1\fP are only
 186 examples of how STREAMS devices can be named; STREAMS
 187 naming conventions may vary among systems conforming to the IEEE\ Std\ 1003.1-2001.
 188 .LP
 189 .IP " 3." 4
 190 Uses the \fIret\fP variable to determine whether an event has occurred
 191 on either of the two STREAMS. The \fIpoll\fP() function
 192 is given 500 milliseconds to wait for an event to occur (if it has
 193 not occurred prior to the \fIpoll\fP() call).
 194 .LP
 195 .IP " 4." 4
 196 Checks the returned value of \fIret\fP. If a positive value is returned,
 197 one of the following can be done:
 198 .RS
 199 .IP " a." 4
 200 Priority data can be written to the open STREAM on priority bands
 201 greater than 0, because the POLLWRBAND event occurred on the
 202 open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]).
 203 .LP
 204 .IP " b." 4
 205 Data can be written to the open STREAM on priority-band 0, because
 206 the POLLOUT event occurred on the open STREAM ( \fIfds\fP[0]
 207 or \fIfds\fP[1]).
 208 .LP
 209 .RE
 210 .LP
 211 .IP " 5." 4
 212 If the returned value is not a positive value, permission to write
 213 data to the open STREAM (on any priority band) is denied.
 214 .LP
 215 .IP " 6." 4
 216 If the POLLHUP event occurs on the open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]),
 217 the device on the open STREAM has
 218 disconnected.
 219 .LP
 220 .sp
 221 .RS
 222 .nf
 223
 224 \fB#include <stropts.h>
 225 #include <poll.h>
 226 \&...
 227 struct pollfd fds[2];
 228 int timeout_msecs = 500;
 229 int ret;
 230     int i;
 231 .sp
 232
 233 /* Open STREAMS device. */
 234 fds[0].fd = open("/dev/dev0", ...);
 235 fds[1].fd = open("/dev/dev1", ...);
 236     fds[0].events = POLLOUT | POLLWRBAND;
 237     fds[1].events = POLLOUT | POLLWRBAND;
 238 .sp
 239
 240 ret = poll(fds, 2, timeout_msecs);
 241 .sp
 242
 243 if (ret > 0) {
 244     /* An event on one of the fds has occurred. */
 245     for (i=0; i<2; i++) {
 246         if (fds[i].revents & POLLWRBAND) {
 247         /* Priority data may be written on device number i. */
 248 \&...
 249         }
 250         if (fds[i].revents & POLLOUT) {
 251         /* Data may be written on device number i. */
 252 \&...
 253         }
 254         if (fds[i].revents & POLLHUP) {
 255         /* A hangup has occurred on device number i. */
 256 \&...
 257         }
 258     }
 259 }
 260 \fP
 261 .fi
 262 .RE
 263 .SH APPLICATION USAGE
 264 .LP
 265 None.
 266 .SH RATIONALE
 267 .LP
 268 None.
 269 .SH FUTURE DIRECTIONS
 270 .LP
 271 None.
 272 .SH SEE ALSO
 273 .LP
 274 \fISTREAMS\fP , \fIgetmsg\fP() , \fIputmsg\fP() , \fIread\fP() , \fIselect\fP()
 275 , \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
 276 \fI<poll.h>\fP, \fI<stropts.h>\fP
 277 .SH COPYRIGHT
 278 Portions of this text are reprinted and reproduced in electronic form
 279 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 280 -- Portable Operating System Interface (POSIX), The Open Group Base
 281 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 282 Electrical and Electronics Engineers, Inc and The Open Group. In the
 283 event of any discrepancy between this version and the original IEEE and
 284 The Open Group Standard, the original IEEE and The Open Group Standard
 285 is the referee document. The original Standard can be obtained online at
 286 http://www.opengroup.org/unix/online.html .