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
11

NAME

13       poll — input/output multiplexing
14

SYNOPSIS

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

DESCRIPTION

21       The poll() function provides applications with a mechanism  for  multi‐
22       plexing input/output over a set of file descriptors. For each member of
23       the array pointed to by  fds,  poll()  shall  examine  the  given  file
24       descriptor  for the event(s) specified in events.  The number of pollfd
25       structures in the fds array is specified by nfds.  The poll()  function
26       shall  identify those file descriptors on which an application can read
27       or write data, or on which certain events have occurred.
28
29       The fds argument specifies the file descriptors to be examined and  the
30       events  of  interest  for  each  file descriptor. It is a pointer to an
31       array with one member for each open file descriptor  of  interest.  The
32       array's members are pollfd structures within which fd specifies an open
33       file descriptor and events and  revents  are  bitmasks  constructed  by
34       OR'ing a combination of the following event flags:
35
36       POLLIN      Data  other  than  high-priority  data  may be read without
37                   blocking.
38
39                   For STREAMS, this flag is set in revents even if  the  mes‐
40                   sage  is  of  zero length. This flag shall be equivalent to
41                   POLLRDNORM | POLLRDBAND.
42
43       POLLRDNORM  Normal data may be read without blocking.
44
45                   For STREAMS, data on priority band 0 may  be  read  without
46                   blocking.  This  flag is set in revents even if the message
47                   is of zero length.
48
49       POLLRDBAND  Priority data may be read without blocking.
50
51                   For STREAMS, data on priority bands greater than 0  may  be
52                   read  without blocking. This flag is set in revents even if
53                   the message is of zero length.
54
55       POLLPRI     High-priority data may be read without blocking.
56
57                   For STREAMS, this flag is set in revents even if  the  mes‐
58                   sage is of zero length.
59
60       POLLOUT     Normal data may be written without blocking.
61
62                   For STREAMS, data on priority band 0 may be written without
63                   blocking.
64
65       POLLWRNORM  Equivalent to POLLOUT.
66
67       POLLWRBAND  Priority data may be written.
68
69                   For STREAMS, data on priority bands greater than 0  may  be
70                   written  without  blocking.  If  any priority band has been
71                   written to on this STREAM, this event only  examines  bands
72                   that have been written to at least once.
73
74       POLLERR     An error has occurred on the device or stream. This flag is
75                   only valid in the revents bitmask; it shall be  ignored  in
76                   the events member.
77
78       POLLHUP     A  device has been disconnected, or a pipe or FIFO has been
79                   closed by the last process that had it  open  for  writing.
80                   Once  set,  the  hangup state of a FIFO shall persist until
81                   some process opens the FIFO for writing or until all  read-
82                   only  file  descriptors for the FIFO are closed. This event
83                   and POLLOUT are mutually-exclusive; a stream can  never  be
84                   writable  if a hangup has occurred. However, this event and
85                   POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI  are  not  mutu‐
86                   ally-exclusive. This flag is only valid in the revents bit‐
87                   mask; it shall be ignored in the events member.
88
89       POLLNVAL    The specified fd value is invalid. This flag is only  valid
90                   in  the revents member; it shall ignored in the events mem‐
91                   ber.
92
93       The significance and semantics of normal, priority,  and  high-priority
94       data are file and device-specific.
95
96       If the value of fd is less than 0, events shall be ignored, and revents
97       shall be set to 0 in that entry on return from poll().
98
99       In each pollfd structure, poll() shall clear the revents member, except
100       that where the application requested a report on a condition by setting
101       one of the bits of events listed above, poll()  shall  set  the  corre‐
102       sponding  bit  in  revents if the requested condition is true. In addi‐
103       tion, poll() shall set the  POLLHUP,  POLLERR,  and  POLLNVAL  flag  in
104       revents  if  the condition is true, even if the application did not set
105       the corresponding bit in events.
106
107       If none of the defined  events  have  occurred  on  any  selected  file
108       descriptor,  poll()  shall  wait  at  least timeout milliseconds for an
109       event to occur on any of the selected file descriptors. If the value of
110       timeout  is 0, poll() shall return immediately. If the value of timeout
111       is −1, poll() shall block until a requested event occurs or  until  the
112       call is interrupted.
113
114       Implementations  may  place  limitations  on the granularity of timeout
115       intervals. If the requested timeout interval requires a finer granular‐
116       ity than the implementation supports, the actual timeout interval shall
117       be rounded up to the next supported value.
118
119       The poll() function shall not be affected by the O_NONBLOCK flag.
120
121       The poll() function shall support regular files, terminal  and  pseudo-
122       terminal  devices,  FIFOs, pipes, sockets and STREAMS-based files.  The
123       behavior of poll() on elements of fds that refer to other types of file
124       is unspecified.
125
126       Regular files shall always poll TRUE for reading and writing.
127
128       A  file descriptor for a socket that is listening for connections shall
129       indicate that it is ready for reading, once connections are  available.
130       A  file descriptor for a socket that is connecting asynchronously shall
131       indicate that it is ready for  writing,  once  a  connection  has  been
132       established.
133

RETURN VALUE

135       Upon successful completion, poll() shall return a non-negative value. A
136       positive value indicates the total number of file descriptors that have
137       been  selected  (that is, file descriptors for which the revents member
138       is non-zero). A value of 0 indicates that the call  timed  out  and  no
139       file  descriptors have been selected. Upon failure, poll() shall return
140       −1 and set errno to indicate the error.
141

ERRORS

143       The poll() function shall fail if:
144
145       EAGAIN The allocation of internal data structures failed but  a  subse‐
146              quent request may succeed.
147
148       EINTR  A signal was caught during poll().
149
150       EINVAL The  nfds  argument is greater than {OPEN_MAX}, or one of the fd
151              members refers  to  a  STREAM  or  multiplexer  that  is  linked
152              (directly or indirectly) downstream from a multiplexer.
153
154       The following sections are informative.
155

EXAMPLES

157   Checking for Events on a Stream
158       The  following  example  opens a pair of STREAMS devices and then waits
159       for either one to become writable. This example proceeds as follows:
160
161        1. Sets the timeout parameter to 500 milliseconds.
162
163        2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and  then  polls
164           them, specifying POLLOUT and POLLWRBAND as the events of interest.
165
166           The  STREAMS device names /dev/dev0 and /dev/dev1 are only examples
167           of how STREAMS devices can be named; STREAMS naming conventions may
168           vary among systems conforming to the POSIX.1‐2008.
169
170        3. Uses the ret variable to determine whether an event has occurred on
171           either of the two STREAMS. The poll() function is  given  500  mil‐
172           liseconds  to  wait  for  an event to occur (if it has not occurred
173           prior to the poll() call).
174
175        4. Checks the returned value of ret.  If a positive value is returned,
176           one of the following can be done:
177
178            a. Priority  data  can  be  written to the open STREAM on priority
179               bands greater than 0, because the POLLWRBAND event occurred  on
180               the open STREAM (fds[0] or fds[1]).
181
182            b. Data  can  be  written  to  the open STREAM on priority-band 0,
183               because the POLLOUT event occurred on the open  STREAM  (fds[0]
184               or fds[1]).
185
186        5. If  the returned value is not a positive value, permission to write
187           data to the open STREAM (on any priority band) is denied.
188
189        6. If the POLLHUP event occurs on the open STREAM (fds[0] or  fds[1]),
190           the device on the open STREAM has disconnected.
191
192           #include <stropts.h>
193           #include <poll.h>
194           ...
195           struct pollfd fds[2];
196           int timeout_msecs = 500;
197           int ret;
198               int i;
199
200           /* Open STREAMS device. */
201           fds[0].fd = open("/dev/dev0", ...);
202           fds[1].fd = open("/dev/dev1", ...);
203           fds[0].events = POLLOUT | POLLWRBAND;
204           fds[1].events = POLLOUT | POLLWRBAND;
205
206           ret = poll(fds, 2, timeout_msecs);
207
208           if (ret > 0) {
209               /* An event on one of the fds has occurred. */
210               for (i=0; i<2; i++) {
211                   if (fds[i].revents & POLLWRBAND) {
212                   /* Priority data may be written on device number i. */
213           ...
214                   }
215                   if (fds[i].revents & POLLOUT) {
216                   /* Data may be written on device number i. */
217           ...
218                   }
219                   if (fds[i].revents & POLLHUP) {
220                   /* A hangup has occurred on device number i. */
221           ...
222                   }
223               }
224           }
225

APPLICATION USAGE

227       None.
228

RATIONALE

230       The POLLHUP event does not occur for FIFOs just because the FIFO is not
231       open for writing. It only occurs when the FIFO is closed  by  the  last
232       writer  and  persists  until some process opens the FIFO for writing or
233       until all read-only file descriptors for the FIFO are closed.
234

FUTURE DIRECTIONS

236       None.
237

SEE ALSO

239       Section 2.6, STREAMS, getmsg(), pselect(), putmsg(), read(), write()
240
241       The Base Definitions volume of POSIX.1‐2008, <poll.h>, <stropts.h>
242
244       Portions of this text are reprinted and reproduced in  electronic  form
245       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
246       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
247       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
248       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
249       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
250       event of any discrepancy between this version and the original IEEE and
251       The  Open Group Standard, the original IEEE and The Open Group Standard
252       is the referee document. The original Standard can be  obtained  online
253       at http://www.unix.org/online.html .
254
255       Any  typographical  or  formatting  errors that appear in this page are
256       most likely to have been introduced during the conversion of the source
257       files  to  man page format. To report such errors, see https://www.ker
258       nel.org/doc/man-pages/reporting_bugs.html .
259
260
261
262IEEE/The Open Group                  2013                             POLL(3P)
Impressum