1POLL(3P)                   POSIX Programmer's Manual                  POLL(3P)
2
3
4

PROLOG

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

NAME

12       poll — input/output multiplexing
13

SYNOPSIS

15       #include <poll.h>
16
17       int poll(struct pollfd fds[], nfds_t nfds, int timeout);
18

DESCRIPTION

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
28       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
35       POLLIN      Data  other  than  high-priority  data  may be read without
36                   blocking.
37
38                   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
42       POLLRDNORM  Normal data may be read without blocking.
43
44                   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
48       POLLRDBAND  Priority data may be read without blocking.
49
50                   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
54       POLLPRI     High-priority data may be read without blocking.
55
56                   For STREAMS, this flag is set in revents even if  the  mes‐
57                   sage is of zero length.
58
59       POLLOUT     Normal data may be written without blocking.
60
61                   For STREAMS, data on priority band 0 may be written without
62                   blocking.
63
64       POLLWRNORM  Equivalent to POLLOUT.
65
66       POLLWRBAND  Priority data may be written.
67
68                   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
73       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
77       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
88       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
92       The significance and semantics of normal, priority,  and  high-priority
93       data are file and device-specific.
94
95       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
98       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
106       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
113       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
118       The poll() function shall not be affected by the O_NONBLOCK flag.
119
120       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
125       Regular files shall always poll TRUE for reading and writing.
126
127       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
133       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

RETURN VALUE

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

ERRORS

146       The poll() function shall fail if:
147
148       EAGAIN The allocation of internal data structures failed but  a  subse‐
149              quent request may succeed.
150
151       EINTR  A signal was caught during poll().
152
153       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
157       The following sections are informative.
158

EXAMPLES

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
164        1. Sets the timeout parameter to 500 milliseconds.
165
166        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
169           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
173        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
178        4. Checks the returned value of ret.  If a positive value is returned,
179           one of the following can be done:
180
181            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
185            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
189        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
192        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
195
196           #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
204           /* 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
210           ret = poll(fds, 2, timeout_msecs);
211
212           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

APPLICATION USAGE

231       None.
232

RATIONALE

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

FUTURE DIRECTIONS

240       None.
241

SEE ALSO

243       Section 2.6, STREAMS, getmsg(), pselect(), putmsg(), read(), write()
244
245       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
258       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 .
262
263
264
265IEEE/The Open Group                  2017                             POLL(3P)
Impressum