Originální popis anglicky:
poll - input/output multiplexing
Návod, kniha: POSIX Programmer's Manual
#include <poll.h>
int poll(struct pollfd
fds[], nfds_t
nfds , int timeout);
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
- The device has been disconnected. 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.
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.
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.
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 IEEE Std 1003.1-2001.
- 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. */
...
}
}
}
None.
None.
None.
STREAMS ,
getmsg() ,
putmsg() ,
read() ,
select() ,
write() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<poll.h>,
<stropts.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html
.
