poll(3posix)
NAME
poll --- input/output multiplexing
SYNOPSIS
#include <poll.h> int poll(struct pollfd fds[], nfds_t nfds, int timeout);
DESCRIPTION
The poll() function provides applications with a mechanism for
multiplexing input/output over a set of file descriptors. For each
member of the array pointed to by fds, poll() shall examine the given
file descriptor for the event(s) specified in events. The number of
pollfd structures in the fds array is specified by nfds. The poll()
function shall identify those file descriptors on which an application
can read or write data, or on which certain events have occurred.
The fds argument specifies the file descriptors to be examined and the
events of interest for each file descriptor. It is a pointer to an
array with one member for each open file descriptor of interest. The
array's members are pollfd structures within which fd specifies an open
file descriptor and events and revents are bitmasks constructed by
OR'ing a combination of the following event flags:
POLLIN Data other than high-priority data may be read without
blocking.
For STREAMS, this flag is set in revents even if the
message is of zero length. This flag shall be equivalent to
POLLRDNORM | POLLRDBAND.
POLLRDNORM Normal data may be read without blocking.
For STREAMS, data on priority band 0 may be read without
blocking. This flag is set in revents even if the message
is of zero length.
POLLRDBAND Priority data may be read without blocking.
For STREAMS, data on priority bands greater than 0 may be
read without blocking. This flag is set in revents even if
the message is of zero length.
POLLPRI High-priority data may be read without blocking.
For STREAMS, this flag is set in revents even if the
message is of zero length.
POLLOUT Normal data may be written without blocking.
For STREAMS, data on priority band 0 may be written without
blocking.
POLLWRNORM Equivalent to POLLOUT.
POLLWRBAND Priority data may be written.
For STREAMS, data on priority bands greater than 0 may be
written without blocking. If any priority band has been
written to on this STREAM, this event only examines bands
that have been written to at least once.
POLLERR An error has occurred on the device or stream. This flag is
only valid in the revents bitmask; it shall be ignored in
the events member.
POLLHUP A device has been disconnected, or a pipe or FIFO has been
closed by the last process that had it open for writing.
Once set, the hangup state of a FIFO shall persist until
some process opens the FIFO for writing or until all read-
only file descriptors for the FIFO are closed. This event
and POLLOUT are mutually-exclusive; a stream can never be
writable if a hangup has occurred. However, this event and
POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not
mutually-exclusive. This flag is only valid in the revents
bitmask; it shall be ignored in the events member.
POLLNVAL The specified fd value is invalid. This flag is only valid
in the revents member; it shall ignored in the events
member.
The significance and semantics of normal, priority, and high-priority
data are file and device-specific.
If the value of fd is less than 0, events shall be ignored, and revents
shall be set to 0 in that entry on return from poll().
In each pollfd structure, poll() shall clear the revents member, except
that where the application requested a report on a condition by setting
one of the bits of events listed above, poll() shall set the
corresponding bit in revents if the requested condition is true. In
addition, poll() shall set the POLLHUP, POLLERR, and POLLNVAL flag in
revents if the condition is true, even if the application did not set
the corresponding bit in events.
If none of the defined events have occurred on any selected file
descriptor, poll() shall wait at least timeout milliseconds for an
event to occur on any of the selected file descriptors. If the value of
timeout is 0, poll() shall return immediately. If the value of timeout
is 1, poll() shall block until a requested event occurs or until the
call is interrupted.
Implementations may place limitations on the granularity of timeout
intervals. If the requested timeout interval requires a finer
granularity than the implementation supports, the actual timeout
interval shall be rounded up to the next supported value.
The poll() function shall not be affected by the O_NONBLOCK flag.
The poll() function shall support regular files, terminal and pseudo-
terminal devices, FIFOs, pipes, sockets and STREAMS-based files. The
behavior of poll() on elements of fds that refer to other types of file
is unspecified.
Regular files shall always poll TRUE for reading and writing.
A file descriptor for a socket that is listening for connections shall
indicate that it is ready for reading, once connections are available.
A file descriptor for a socket that is connecting asynchronously shall
indicate that it is ready for writing, once a connection has been
established.
RETURN VALUE
Upon successful completion, poll() shall return a non-negative value. A positive value indicates the total number of file descriptors that have been selected (that is, file descriptors for which the revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors have been selected. Upon failure, poll() shall return 1 and set errno to indicate the error.
ERRORS
The poll() function shall fail if:
EAGAIN The allocation of internal data structures failed but a
subsequent request may succeed.
EINTR A signal was caught during poll().
EINVAL The nfds argument is greater than {OPEN_MAX}, or one of the fd
members refers to a STREAM or multiplexer that is linked
(directly or indirectly) downstream from a multiplexer.
The following sections are informative.
EXAMPLES
Checking for Events on a Stream
The following example opens a pair of STREAMS devices and then waits
for either one to become writable. This example proceeds as follows:
1. Sets the timeout parameter to 500 milliseconds.
2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and then polls
them, specifying POLLOUT and POLLWRBAND as the events of interest.
The STREAMS device names /dev/dev0 and /dev/dev1 are only examples
of how STREAMS devices can be named; STREAMS naming conventions may
vary among systems conforming to the POSIX.12008.
3. Uses the ret variable to determine whether an event has occurred on
either of the two STREAMS. The poll() function is given 500
milliseconds to wait for an event to occur (if it has not occurred
prior to the poll() call).
4. Checks the returned value of ret. If a positive value is returned,
one of the following can be done:
a. Priority data can be written to the open STREAM on priority
bands greater than 0, because the POLLWRBAND event occurred on
the open STREAM (fds[0] or fds[1]).
b. Data can be written to the open STREAM on priority-band 0,
because the POLLOUT event occurred on the open STREAM (fds[0]
or fds[1]).
5. If the returned value is not a positive value, permission to write
data to the open STREAM (on any priority band) is denied.
6. If the POLLHUP event occurs on the open STREAM (fds[0] or fds[1]),
the device on the open STREAM has disconnected.
#include <stropts.h>
#include <poll.h>
...
struct pollfd fds[2];
int timeout_msecs = 500;
int ret;
int i;
/* Open STREAMS device. */
fds[0].fd = open("/dev/dev0", ...);
fds[1].fd = open("/dev/dev1", ...);
fds[0].events = POLLOUT | POLLWRBAND;
fds[1].events = POLLOUT | POLLWRBAND;
ret = poll(fds, 2, timeout_msecs);
if (ret > 0) {
/* An event on one of the fds has occurred. */
for (i=0; i<2; i++) {
if (fds[i].revents & POLLWRBAND) {
/* Priority data may be written on device number i. */
...
}
if (fds[i].revents & POLLOUT) {
/* Data may be written on device number i. */
...
}
if (fds[i].revents & POLLHUP) {
/* A hangup has occurred on device number i. */
...
}
}
}
APPLICATION USAGE
None.
RATIONALE
The POLLHUP event does not occur for FIFOs just because the FIFO is not open for writing. It only occurs when the FIFO is closed by the last writer and persists until some process opens the FIFO for writing or until all read-only file descriptors for the FIFO are closed.
FUTURE DIRECTIONS
None.
SEE ALSO
Section 2.6, STREAMS, getmsg(), pselect(), putmsg(), read(), write() The Base Definitions volume of POSIX.12008, <poll.h>, <stropts.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.unix.org/online.html . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
