path: root/man3p/poll.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "POLL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" poll 
.SH NAME
poll \- input/output multiplexing
.SH SYNOPSIS
.LP
\fB#include <poll.h>
.br
.sp
int poll(struct pollfd\fP \fIfds\fP\fB[], nfds_t\fP \fInfds\fP\fB,
int\fP \fItimeout\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpoll\fP() 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 \fIfds\fP, \fIpoll\fP()
shall examine the given file descriptor for the event(s)
specified in \fIevents\fP. The number of \fBpollfd\fP structures in
the \fIfds\fP array is specified by \fInfds\fP. The
\fIpoll\fP() function shall identify those file descriptors on which
an application can read or write data, or on which certain
events have occurred.
.LP
The \fIfds\fP 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 \fBpollfd\fP structures
within which \fIfd\fP specifies an open file descriptor and \fIevents\fP
and \fIrevents\fP are bitmasks constructed by OR'ing a
combination of the following event flags:
.TP 7
POLLIN
Data other than high-priority data may be read without blocking. 
.LP
For STREAMS, this flag is set in \fIrevents\fP even if the message
is of zero length. This flag shall be equivalent to POLLRDNORM
| POLLRDBAND. 
.TP 7
POLLRDNORM
Normal data may be read without blocking. 
.LP
For STREAMS, data on priority band 0 may be read without blocking.
This flag is set in \fIrevents\fP even if the message is of
zero length. 
.TP 7
POLLRDBAND
Priority data may be read without blocking. 
.LP
For STREAMS, data on priority bands greater than 0 may be read without
blocking. This flag is set in \fIrevents\fP even if the
message is of zero length. 
.TP 7
POLLPRI
High-priority data may be read without blocking. 
.LP
For STREAMS, this flag is set in \fIrevents\fP even if the message
is of zero length. 
.TP 7
POLLOUT
Normal data may be written without blocking. 
.LP
For STREAMS, data on priority band 0 may be written without blocking.
.TP 7
POLLWRNORM
Equivalent to POLLOUT.
.TP 7
POLLWRBAND
Priority data may be written. 
.LP
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. 
.TP 7
POLLERR
An error has occurred on the device or stream. This flag is only valid
in the \fIrevents\fP bitmask; it shall be ignored in
the \fIevents\fP member.
.TP 7
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 \fIrevents\fP bitmask; it shall be ignored in the \fIevents\fP
member.
.TP 7
POLLNVAL
The specified \fIfd\fP value is invalid. This flag is only valid in
the \fIrevents\fP member; it shall ignored in the
\fIevents\fP member.
.sp
.LP
The significance and semantics of normal, priority, and high-priority
data are file and device-specific.
.LP
If the value of \fIfd\fP is less than 0, \fIevents\fP shall be ignored,
and \fIrevents\fP shall be set to 0 in that entry on
return from \fIpoll\fP().
.LP
In each \fBpollfd\fP structure, \fIpoll\fP() shall clear the \fIrevents\fP
member, except that where the application
requested a report on a condition by setting one of the bits of \fIevents\fP
listed above, \fIpoll\fP() shall set the
corresponding bit in \fIrevents\fP if the requested condition is true.
In addition, \fIpoll\fP() shall set the POLLHUP, POLLERR,
and POLLNVAL flag in \fIrevents\fP if the condition is true, even
if the application did not set the corresponding bit in
\fIevents\fP.
.LP
If none of the defined events have occurred on any selected file descriptor,
\fIpoll\fP() shall wait at least \fItimeout\fP
milliseconds for an event to occur on any of the selected file descriptors.
If the value of \fItimeout\fP is 0, \fIpoll\fP()
shall return immediately. If the value of \fItimeout\fP is -1, \fIpoll\fP()
shall block until a requested event occurs or until
the call is interrupted.
.LP
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.
.LP
The \fIpoll\fP() function shall not be affected by the O_NONBLOCK
flag.
.LP
The \fIpoll\fP() function shall support regular files, terminal and
pseudo-terminal devices, FIFOs, pipes, sockets and  
\ STREAMS-based files.  The behavior of \fIpoll\fP() on
elements of \fIfds\fP that refer to other types of file is unspecified.
.LP
Regular files shall always poll TRUE for reading and writing.
.LP
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.
.SH RETURN VALUE
.LP
Upon successful completion, \fIpoll\fP() 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 \fIrevents\fP member is non-zero). A value of 0
indicates that the call timed out and no file descriptors have been
selected. Upon failure, \fIpoll\fP() shall return -1 and set
\fIerrno\fP to indicate the error.
.SH ERRORS
.LP
The \fIpoll\fP() function shall fail if:
.TP 7
.B EAGAIN
The allocation of internal data structures failed but a subsequent
request may succeed.
.TP 7
.B EINTR
A signal was caught during \fIpoll\fP().
.TP 7
.B EINVAL
The \fInfds\fP argument is greater than {OPEN_MAX},   \ or one of
the \fIfd\fP members refers to a STREAM or multiplexer
that is linked (directly or indirectly) downstream from a multiplexer.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.SS Checking for Events on a Stream
.LP
The following example opens a pair of STREAMS devices and then waits
for either one to become writable. This example proceeds as
follows:
.IP " 1." 4
Sets the \fItimeout\fP parameter to 500 milliseconds.
.LP
.IP " 2." 4
Opens the STREAMS devices \fB/dev/dev0\fP and \fB/dev/dev1\fP, and
then polls them, specifying POLLOUT and POLLWRBAND as the
events of interest.
.LP
The STREAMS device names \fB/dev/dev0\fP and \fB/dev/dev1\fP 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.
.LP
.IP " 3." 4
Uses the \fIret\fP variable to determine whether an event has occurred
on either of the two STREAMS. The \fIpoll\fP() function
is given 500 milliseconds to wait for an event to occur (if it has
not occurred prior to the \fIpoll\fP() call).
.LP
.IP " 4." 4
Checks the returned value of \fIret\fP. If a positive value is returned,
one of the following can be done:
.RS
.IP " a." 4
Priority data can be written to the open STREAM on priority bands
greater than 0, because the POLLWRBAND event occurred on the
open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]).
.LP
.IP " b." 4
Data can be written to the open STREAM on priority-band 0, because
the POLLOUT event occurred on the open STREAM ( \fIfds\fP[0]
or \fIfds\fP[1]).
.LP
.RE
.LP
.IP " 5." 4
If the returned value is not a positive value, permission to write
data to the open STREAM (on any priority band) is denied.
.LP
.IP " 6." 4
If the POLLHUP event occurs on the open STREAM ( \fIfds\fP[0] or \fIfds\fP[1]),
the device on the open STREAM has
disconnected.
.LP
.sp
.RS
.nf

\fB#include <stropts.h>
#include <poll.h>
\&...
struct pollfd fds[2];
int timeout_msecs = 500;
int ret;
    int i;
.sp

/* 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;
.sp

ret = poll(fds, 2, timeout_msecs);
.sp

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. */
\&...
        }
    }
}
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fISTREAMS\fP , \fIgetmsg\fP() , \fIputmsg\fP() , \fIread\fP() , \fIselect\fP()
, \fIwrite\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<poll.h>\fP, \fI<stropts.h>\fP
.SH COPYRIGHT
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 .