1POLL(P) POSIX Programmer's Manual POLL(P)
2
6 poll - input/output multiplexing
7
9 #include <poll.h>
10 int poll(struct pollfd fds[], nfds_t nfds, int timeout);
12
15 The poll() function provides applications with a mechanism for multi‐
16 plexing input/output over a set of file descriptors. For each member
17 of the array pointed to by fds, poll() shall examine the given file
18 descriptor for the event(s) specified in events. The number of pollfd
19 structures in the fds array is specified by nfds. The poll() function
20 shall identify those file descriptors on which an application can read
21 or write data, or on which certain events have occurred.
22 The fds argument specifies the file descriptors to be examined and the
24 events of interest for each file descriptor. It is a pointer to an
25 array with one member for each open file descriptor of interest. The
26 array's members are pollfd structures within which fd specifies an open
27 file descriptor and events and revents are bitmasks constructed by
28 OR'ing a combination of the following event flags:
29 POLLIN Data other than high-priority data may be read without blocking.
31 For STREAMS, this flag is set in revents even if the message is of zero
33 length. This flag shall be equivalent to POLLRDNORM | POLLRDBAND.
34 POLLRDNORM
36 Normal data may be read without blocking.
37 For STREAMS, data on priority band 0 may be read without blocking.
39 This flag is set in revents even if the message is of zero length.
40 POLLRDBAND
42 Priority data may be read without blocking.
43 For STREAMS, data on priority bands greater than 0 may be read without
45 blocking. This flag is set in revents even if the message is of zero
46 length.
47 POLLPRI
49 High-priority data may be read without blocking.
50 For STREAMS, this flag is set in revents even if the message is of zero
52 length.
53 POLLOUT
55 Normal data may be written without blocking.
56 For STREAMS, data on priority band 0 may be written without blocking.
58 POLLWRNORM
60 Equivalent to POLLOUT.
61 POLLWRBAND
63 Priority data may be written.
64 For STREAMS, data on priority bands greater than 0 may be written with‐
66 out blocking. If any priority band has been written to on this STREAM,
67 this event only examines bands that have been written to at least once.
68 POLLERR
70 An error has occurred on the device or stream. This flag is only
71 valid in the revents bitmask; it shall be ignored in the events
72 member.
73 POLLHUP
75 The device has been disconnected. This event and POLLOUT are
76 mutually-exclusive; a stream can never be writable if a hangup
77 has occurred. However, this event and POLLIN, POLLRDNORM, POLL‐
78 RDBAND, or POLLPRI are not mutually-exclusive. This flag is only
79 valid in the revents bitmask; it shall be ignored in the events
80 member.
81 POLLNVAL
83 The specified fd value is invalid. This flag is only valid in
84 the revents member; it shall ignored in the events member.
85 The significance and semantics of normal, priority, and high-priority
88 data are file and device-specific.
89 If the value of fd is less than 0, events shall be ignored, and revents
91 shall be set to 0 in that entry on return from poll().
92 In each pollfd structure, poll() shall clear the revents member, except
94 that where the application requested a report on a condition by setting
95 one of the bits of events listed above, poll() shall set the corre‐
96 sponding bit in revents if the requested condition is true. In addi‐
97 tion, poll() shall set the POLLHUP, POLLERR, and POLLNVAL flag in
98 revents if the condition is true, even if the application did not set
99 the corresponding bit in events.
100 If none of the defined events have occurred on any selected file
102 descriptor, poll() shall wait at least timeout milliseconds for an
103 event to occur on any of the selected file descriptors. If the value
104 of timeout is 0, poll() shall return immediately. If the value of time‐
105 out is -1, poll() shall block until a requested event occurs or until
106 the call is interrupted.
107 Implementations may place limitations on the granularity of timeout
109 intervals. If the requested timeout interval requires a finer granular‐
110 ity than the implementation supports, the actual timeout interval shall
111 be rounded up to the next supported value.
112 The poll() function shall not be affected by the O_NONBLOCK flag.
114 The poll() function shall support regular files, terminal and pseudo-
116 terminal devices, FIFOs, pipes, sockets and STREAMS-based files. The
117 behavior of poll() on elements of fds that refer to other types of file
118 is unspecified.
119 Regular files shall always poll TRUE for reading and writing.
121 A file descriptor for a socket that is listening for connections shall
123 indicate that it is ready for reading, once connections are available.
124 A file descriptor for a socket that is connecting asynchronously shall
125 indicate that it is ready for writing, once a connection has been
126 established.
127
129 Upon successful completion, poll() shall return a non-negative value. A
130 positive value indicates the total number of file descriptors that have
131 been selected (that is, file descriptors for which the revents member
132 is non-zero). A value of 0 indicates that the call timed out and no
133 file descriptors have been selected. Upon failure, poll() shall return
134 -1 and set errno to indicate the error.
135
137 The poll() function shall fail if:
138 EAGAIN The allocation of internal data structures failed but a subse‐
140 quent request may succeed.
141 EINTR A signal was caught during poll().
143 EINVAL The nfds argument is greater than {OPEN_MAX}, or one of the
145 fd members refers to a STREAM or multiplexer that is linked
146 (directly or indirectly) downstream from a multiplexer.
147 The following sections are informative.
150
152 Checking for Events on a Stream
153 The following example opens a pair of STREAMS devices and then waits
154 for either one to become writable. This example proceeds as follows:
155 1. Sets the timeout parameter to 500 milliseconds.
157 2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and then polls
159 them, specifying POLLOUT and POLLWRBAND as the events of interest.
160 The STREAMS device names /dev/dev0 and /dev/dev1 are only examples of
162 how STREAMS devices can be named; STREAMS naming conventions may vary
163 among systems conforming to the IEEE Std 1003.1-2001.
164 3. Uses the ret variable to determine whether an event has occurred on
166 either of the two STREAMS. The poll() function is given 500 mil‐
167 liseconds to wait for an event to occur (if it has not occurred
168 prior to the poll() call).
169 4. Checks the returned value of ret. If a positive value is returned,
171 one of the following can be done:
172 a. Priority data can be written to the open STREAM on priority
174 bands greater than 0, because the POLLWRBAND event occurred on
175 the open STREAM ( fds[0] or fds[1]).
176 b. Data can be written to the open STREAM on priority-band 0,
178 because the POLLOUT event occurred on the open STREAM ( fds[0]
179 or fds[1]).
180 5. If the returned value is not a positive value, permission to write
182 data to the open STREAM (on any priority band) is denied.
183 6. If the POLLHUP event occurs on the open STREAM ( fds[0] or fds[1]),
185 the device on the open STREAM has disconnected.
186 #include <stropts.h>
188 #include <poll.h>
189 ...
190 struct pollfd fds[2];
191 int timeout_msecs = 500;
192 int ret;
193 int i;
194 /* Open STREAMS device. */
197 fds[0].fd = open("/dev/dev0", ...);
198 fds[1].fd = open("/dev/dev1", ...);
199 fds[0].events = POLLOUT | POLLWRBAND;
200 fds[1].events = POLLOUT | POLLWRBAND;
201 ret = poll(fds, 2, timeout_msecs);
204 if (ret > 0) {
207 /* An event on one of the fds has occurred. */
208 for (i=0; i<2; i++) {
209 if (fds[i].revents & POLLWRBAND) {
210 /* Priority data may be written on device number i. */
211 ...
212 }
213 if (fds[i].revents & POLLOUT) {
214 /* Data may be written on device number i. */
215 ...
216 }
217 if (fds[i].revents & POLLHUP) {
218 /* A hangup has occurred on device number i. */
219 ...
220 }
221 }
222 }
223
225 None.
226
228 None.
229
231 None.
232
234 STREAMS , getmsg() , putmsg() , read() , select() , write() , the Base
235 Definitions volume of IEEE Std 1003.1-2001, <poll.h>, <stropts.h>
236
238 Portions of this text are reprinted and reproduced in electronic form
239 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
240 -- Portable Operating System Interface (POSIX), The Open Group Base
241 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
242 Electrical and Electronics Engineers, Inc and The Open Group. In the
243 event of any discrepancy between this version and the original IEEE and
244 The Open Group Standard, the original IEEE and The Open Group Standard
245 is the referee document. The original Standard can be obtained online
246 at http://www.opengroup.org/unix/online.html .
247IEEE/The Open Group 2003 POLL(P)