1poll(2) System Calls poll(2)
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() examines the given file descrip‐
18 tor for the event(s) specified in events. The number of pollfd struc‐
19 tures in the fds array is specified by nfds. The poll() function iden‐
20 tifies those file descriptors on which an application can read or write
21 data, or on which certain events have occurred.
22 The fds argument specifies the file descriptors to be examined and the
25 events of interest for each file descriptor. It is a pointer to an
26 array with one member for each open file descriptor of interest. The
27 array's members are pollfd structures, which contain the following mem‐
28 bers:
29 int fd; /* file descriptor */
31 short events; /* requested events */
32 short revents; /* returned events */
33 The fd member specifies an open file descriptor and the events and
37 revents members are bitmasks constructed by a logical OR operation of
38 any combination of the following event flags:
39 POLLIN Data other than high priority data may be read without
41 blocking. For streams, this flag is set in revents even
42 if the message is of zero length.
43 POLLRDNORM Normal data (priority band equals 0) may be read without
46 blocking. For streams, this flag is set in revents even
47 if the message is of zero length.
48 POLLRDBAND Data from a non-zero priority band may be read without
51 blocking. For streams, this flag is set in revents even
52 if the message is of zero length.
53 POLLPRI High priority data may be received without blocking. For
56 streams, this flag is set in revents even if the message
57 is of zero length.
58 POLLOUT Normal data (priority band equals 0) may be written with‐
61 out blocking.
62 POLLWRNORM The same as POLLOUT.
65 POLLWRBAND Priority data (priority band > 0) may be written. This
68 event only examines bands that have been written to at
69 least once.
70 POLLERR An error has occurred on the device or stream. This flag
73 is only valid in the revents bitmask; it is not used in
74 the events member.
75 POLLHUP A hangup has occurred on the stream. This event and
78 POLLOUT are mutually exclusive; a stream can never be
79 writable if a hangup has occurred. However, this event
80 and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not
81 mutually exclusive. This flag is only valid in the
82 revents bitmask; it is not used in the events member.
83 POLLNVAL The specified fd value does not belong to an open file.
86 This flag is only valid in the revents member; it is not
87 used in the events member.
88 If the value fd is less than 0, events is ignored and revents is set to
92 0 in that entry on return from poll().
93 The results of the poll() query are stored in the revents member in the
96 pollfd structure. Bits are set in the revents bitmask to indicate which
97 of the requested events are true. If none are true, none of the speci‐
98 fied bits are set in revents when the poll() call returns. The event
99 flags POLLHUP, POLLERR, and POLLNVAL are always set in revents if
100 the conditions they indicate are true; this occurs even though these
101 flags were not present in events.
102 If none of the defined events have occurred on any selected file
105 descriptor, poll() waits at least timeout milliseconds for an event to
106 occur on any of the selected file descriptors. On a computer where mil‐
107 lisecond timing accuracy is not available, timeout is rounded up to the
108 nearest legal value available on that system. If the value timeout is
109 0, poll() returns immediately. If the value of timeout is −1, poll()
110 blocks until a requested event occurs or until the call is interrupted.
111 The poll() function is not affected by the O_NDELAY and O_NONBLOCK
112 flags.
113 The poll() function supports regular files, terminal and pseudo-termi‐
116 nal devices, streams-based files, FIFOs and pipes. The behavior of
117 poll() on elements of fds that refer to other types of file is unspeci‐
118 fied.
119 The poll() function supports sockets.
122 A file descriptor for a socket that is listening for connections will
125 indicate that it is ready for reading, once connections are available.
126 A file descriptor for a socket that is connecting asynchronously will
127 indicate that it is ready for writing, once a connection has been
128 established.
129 Regular files always poll() TRUE for reading and writing.
132
134 Upon successful completion, a non-negative value is returned. A posi‐
135 tive value indicates the total number of file descriptors that has been
136 selected (that is, file descriptors for which the revents member is
137 non-zero). A value of 0 indicates that the call timed out and no file
138 descriptors have been selected. Upon failure, −1 is returned and errno
139 is set to indicate the error.
140
142 The poll() function will fail if:
143 EAGAIN Allocation of internal data structures failed, but the
145 request may be attempted again.
146 EFAULT Some argument points to an illegal address.
149 EINTR A signal was caught during the poll() function.
152 EINVAL The argument nfds is greater than {OPEN_MAX}, or one of the
155 fd members refers to a stream or multiplexer that is linked
156 (directly or indirectly) downstream from a multiplexer.
157
160 See attributes(5) for descriptions of the following attributes:
161 ┌─────────────────────────────┬─────────────────────────────┐
166 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
167 ├─────────────────────────────┼─────────────────────────────┤
168 │Interface Stability │Standard │
169 └─────────────────────────────┴─────────────────────────────┘
170
172 Intro(2), getmsg(2), getrlimit(2), putmsg(2), read(2), write(2),
173 select(3C), attributes(5), standards(5), chpoll(9E)
174 STREAMS Programming Guide
177
179 Non-STREAMS drivers use chpoll(9E) to implement poll() on these
180 devices.
181SunOS 5.11 23 Aug 2001 poll(2)