1POLL(3P) POSIX Programmer's Manual POLL(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 poll — input/output multiplexing
13
15 #include <poll.h>
16 int poll(struct pollfd fds[], nfds_t nfds, int timeout);
18
20 The poll() function provides applications with a mechanism for multi‐
21 plexing input/output over a set of file descriptors. For each member of
22 the array pointed to by fds, poll() shall examine the given file
23 descriptor for the event(s) specified in events. The number of pollfd
24 structures in the fds array is specified by nfds. The poll() function
25 shall identify those file descriptors on which an application can read
26 or write data, or on which certain events have occurred.
27 The fds argument specifies the file descriptors to be examined and the
29 events of interest for each file descriptor. It is a pointer to an
30 array with one member for each open file descriptor of interest. The
31 array's members are pollfd structures within which fd specifies an open
32 file descriptor and events and revents are bitmasks constructed by
33 OR'ing a combination of the following event flags:
34 POLLIN Data other than high-priority data may be read without
36 blocking.
37 For STREAMS, this flag is set in revents even if the mes‐
39 sage is of zero length. This flag shall be equivalent to
40 POLLRDNORM | POLLRDBAND.
41 POLLRDNORM Normal data may be read without blocking.
43 For STREAMS, data on priority band 0 may be read without
45 blocking. This flag is set in revents even if the message
46 is of zero length.
47 POLLRDBAND Priority data may be read without blocking.
49 For STREAMS, data on priority bands greater than 0 may be
51 read without blocking. This flag is set in revents even if
52 the message is of zero length.
53 POLLPRI High-priority data may be read without blocking.
55 For STREAMS, this flag is set in revents even if the mes‐
57 sage is of zero length.
58 POLLOUT Normal data may be written without blocking.
60 For STREAMS, data on priority band 0 may be written without
62 blocking.
63 POLLWRNORM Equivalent to POLLOUT.
65 POLLWRBAND Priority data may be written.
67 For STREAMS, data on priority bands greater than 0 may be
69 written without blocking. If any priority band has been
70 written to on this STREAM, this event only examines bands
71 that have been written to at least once.
72 POLLERR An error has occurred on the device or stream. This flag is
74 only valid in the revents bitmask; it shall be ignored in
75 the events member.
76 POLLHUP A device has been disconnected, or a pipe or FIFO has been
78 closed by the last process that had it open for writing.
79 Once set, the hangup state of a FIFO shall persist until
80 some process opens the FIFO for writing or until all read-
81 only file descriptors for the FIFO are closed. This event
82 and POLLOUT are mutually-exclusive; a stream can never be
83 writable if a hangup has occurred. However, this event and
84 POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutu‐
85 ally-exclusive. This flag is only valid in the revents bit‐
86 mask; it shall be ignored in the events member.
87 POLLNVAL The specified fd value is invalid. This flag is only valid
89 in the revents member; it shall ignored in the events mem‐
90 ber.
91 The significance and semantics of normal, priority, and high-priority
93 data are file and device-specific.
94 If the value of fd is less than 0, events shall be ignored, and revents
96 shall be set to 0 in that entry on return from poll().
97 In each pollfd structure, poll() shall clear the revents member, except
99 that where the application requested a report on a condition by setting
100 one of the bits of events listed above, poll() shall set the corre‐
101 sponding bit in revents if the requested condition is true. In addi‐
102 tion, poll() shall set the POLLHUP, POLLERR, and POLLNVAL flag in
103 revents if the condition is true, even if the application did not set
104 the corresponding bit in events.
105 If none of the defined events have occurred on any selected file
107 descriptor, poll() shall wait at least timeout milliseconds for an
108 event to occur on any of the selected file descriptors. If the value of
109 timeout is 0, poll() shall return immediately. If the value of timeout
110 is -1, poll() shall block until a requested event occurs or until the
111 call is interrupted.
112 Implementations may place limitations on the granularity of timeout
114 intervals. If the requested timeout interval requires a finer granular‐
115 ity than the implementation supports, the actual timeout interval shall
116 be rounded up to the next supported value.
117 The poll() function shall not be affected by the O_NONBLOCK flag.
119 The poll() function shall support regular files, terminal and pseudo-
121 terminal devices, FIFOs, pipes, sockets and STREAMS-based files. The
122 behavior of poll() on elements of fds that refer to other types of file
123 is unspecified.
124 Regular files shall always poll TRUE for reading and writing.
126 A file descriptor for a socket that is listening for connections shall
128 indicate that it is ready for reading, once connections are available.
129 A file descriptor for a socket that is connecting asynchronously shall
130 indicate that it is ready for writing, once a connection has been
131 established.
132 Provided the application does not perform any action that results in
134 unspecified or undefined behavior, the value of the fd and events mem‐
135 bers of each element of fds shall not be modified by poll().
136
138 Upon successful completion, poll() shall return a non-negative value. A
139 positive value indicates the total number of pollfd structures that
140 have selected events (that is, those for which the revents member is
141 non-zero). A value of 0 indicates that the call timed out and no file
142 descriptors have been selected. Upon failure, poll() shall return -1
143 and set errno to indicate the error.
144
146 The poll() function shall fail if:
147 EAGAIN The allocation of internal data structures failed but a subse‐
149 quent request may succeed.
150 EINTR A signal was caught during poll().
152 EINVAL The nfds argument is greater than {OPEN_MAX}, or one of the fd
154 members refers to a STREAM or multiplexer that is linked
155 (directly or indirectly) downstream from a multiplexer.
156 The following sections are informative.
158
160 Checking for Events on a Stream
161 The following example opens a pair of STREAMS devices and then waits
162 for either one to become writable. This example proceeds as follows:
163 1. Sets the timeout parameter to 500 milliseconds.
165 2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and then polls
167 them, specifying POLLOUT and POLLWRBAND as the events of interest.
168 The STREAMS device names /dev/dev0 and /dev/dev1 are only examples
170 of how STREAMS devices can be named; STREAMS naming conventions may
171 vary among systems conforming to the POSIX.1‐2008.
172 3. Uses the ret variable to determine whether an event has occurred on
174 either of the two STREAMS. The poll() function is given 500 mil‐
175 liseconds to wait for an event to occur (if it has not occurred
176 prior to the poll() call).
177 4. Checks the returned value of ret. If a positive value is returned,
179 one of the following can be done:
180 a. Priority data can be written to the open STREAM on priority
182 bands greater than 0, because the POLLWRBAND event occurred on
183 the open STREAM (fds[0] or fds[1]).
184 b. Data can be written to the open STREAM on priority-band 0,
186 because the POLLOUT event occurred on the open STREAM (fds[0]
187 or fds[1]).
188 5. If the returned value is not a positive value, permission to write
190 data to the open STREAM (on any priority band) is denied.
191 6. If the POLLHUP event occurs on the open STREAM (fds[0] or fds[1]),
193 the device on the open STREAM has disconnected.
194 #include <stropts.h>
197 #include <poll.h>
198 ...
199 struct pollfd fds[2];
200 int timeout_msecs = 500;
201 int ret;
202 int i;
203 /* Open STREAMS device. */
205 fds[0].fd = open("/dev/dev0", ...);
206 fds[1].fd = open("/dev/dev1", ...);
207 fds[0].events = POLLOUT | POLLWRBAND;
208 fds[1].events = POLLOUT | POLLWRBAND;
209 ret = poll(fds, 2, timeout_msecs);
211 if (ret > 0) {
213 /* An event on one of the fds has occurred. */
214 for (i=0; i<2; i++) {
215 if (fds[i].revents & POLLWRBAND) {
216 /* Priority data may be written on device number i. */
217 ...
218 }
219 if (fds[i].revents & POLLOUT) {
220 /* Data may be written on device number i. */
221 ...
222 }
223 if (fds[i].revents & POLLHUP) {
224 /* A hangup has occurred on device number i. */
225 ...
226 }
227 }
228 }
229
231 None.
232
234 The POLLHUP event does not occur for FIFOs just because the FIFO is not
235 open for writing. It only occurs when the FIFO is closed by the last
236 writer and persists until some process opens the FIFO for writing or
237 until all read-only file descriptors for the FIFO are closed.
238
240 None.
241
243 Section 2.6, STREAMS, getmsg(), pselect(), putmsg(), read(), write()
244 The Base Definitions volume of POSIX.1‐2017, <poll.h>, <stropts.h>
246
248 Portions of this text are reprinted and reproduced in electronic form
249 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
250 table Operating System Interface (POSIX), The Open Group Base Specifi‐
251 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
252 Electrical and Electronics Engineers, Inc and The Open Group. In the
253 event of any discrepancy between this version and the original IEEE and
254 The Open Group Standard, the original IEEE and The Open Group Standard
255 is the referee document. The original Standard can be obtained online
256 at http://www.opengroup.org/unix/online.html .
257 Any typographical or formatting errors that appear in this page are
259 most likely to have been introduced during the conversion of the source
260 files to man page format. To report such errors, see https://www.ker‐
261 nel.org/doc/man-pages/reporting_bugs.html .
262IEEE/The Open Group 2017 POLL(3P)