poll(2)

NAME

poll() — monitor I/O conditions on multiple file descriptors

SYNOPSIS

#include <poll.h> 

int poll( 
     struct pollfd fds[], 
     nfds_t nfds, 
     int timeout); 

DESCRIPTION

poll() provides a general mechanism for reporting I/O conditions associated with a set of file descriptors and for waiting until one or more specified conditions becomes true. Specified conditions include the ability to read or write data without blocking, and error conditions.

Parameters

fds: Points to an array of pollfd structures, one for each file descriptor of interest.
nfds: Specifies the number of pollfd structures in the fds array.
timeout: Specifies the maximum length of time (in milliseconds) to wait for at least one of the specified conditions to occur.

Each pollfd structure includes the following members:

int fd: File descriptor
short events: Requested conditions
short revents: Reported conditions

The fd member of each pollfd structure specifies an open file descriptor. The poll() function uses the events member to determine what conditions to report for this file descriptor. If one or more of these conditions is true, poll() sets the associated revents member.

poll() ignores any pollfd structure whose fd member is negative. If the fd member of all pollfd structures is negative, poll() returns 0 and has no other results.

The events and revents members of the pollfd structure are bit masks. The calling process sets the events bit mask, and poll() sets the revents bit masks. These bit masks contain ORed combinations of condition flags. The following condition flags are defined:

POLLIN: Data can be read without blocking. For streams, this flag means that a message that is not high priority is at the front of the stream head read queue. This message can be of zero length.
POLLNORM: Synonym for POLLIN
POLLPRI: A high priority message is available. For streams, this message can be of zero length.
POLLOUT: Data can be written without blocking. For streams, this flag specifies that normal data (not high priority or priority band > 0) can be written without being blocked by flow control. This flag is not used for high priority data, because it can be written even if the stream is flow controlled.
POLLERR: An error has occurred on the file descriptor.
POLLHUP: The device has been disconnected. For streams, this flag in revents is mutually exclusive with POLLOUT, since a stream cannot be written to after a hangup occurs. This flag and POLLIN, POLLPRI, POLLRDNORM, POLLRDBAND, and POLLMSG are not mutually exclusive.
POLLNVAL: fd is not a valid file descriptor.
POLLRDNORM: A non-priority message is available. For streams, this flag means that a normal message (not high priority or priority band > 0) is at the front of the stream head read queue. This message can be of zero length.
POLLRDBAND: A priority message (priority band > 0) is at the front of the stream head read queue. This message can be read without blocking. The message can be of zero length.
POLLWRNORM: Same as POLLOUT
POLLWRBAND: Priority data (priority band > 0) can be written without being blocked by flow control. Only previously written bands are checked.
POLLMSG: A M_SIG or M_PCSIG message specifying SIGPOLL has reached the front of the stream head read queue.

The conditions indicated by POLLNORM and POLLOUT are true if and only if at least one byte of data can be read or written without blocking. The exception is regular files, which always poll true for POLLNORM and POLLOUT. Also, streams return POLLNORM in revents even if the available message is of zero length.

The condition flags POLLERR, POLLHUP, and POLLNVAL are always set in revents if the conditions they indicate are true for the specified file descriptor, whether or not these flags are set in events.

For each call to poll(), the set of reportable conditions for each file descriptor consists of those conditions that are always reported, together with any further conditions for which flags are set in events. If any reportable condition is true for any file descriptor, poll() returns with flags set in revents for each true condition for that file descriptor.

If no reportable condition is true for any of the file descriptors, poll() waits up to timeout milliseconds for a reportable condition to become true. If, in that time interval, a reportable condition becomes true for any of the file descriptors, poll() reports the condition in the file descriptor's associated revents member and returns. If no reportable condition becomes true, poll() returns without setting any revents bit masks.

If the timeout parameter is a value of -1, poll() does not return until at least one specified event has occurred. If the value of the timeout parameter is 0, poll() does not wait for an event to occur but returns immediately, even if no specified event has occurred. The behavior of poll() is not affected by whether the O_NONBLOCK flag is set on any of the specified file descriptors.

RETURN VALUE

Upon successful completion, poll() returns a nonnegative value. If the call returns 0, poll() has timed out and has not set any of the revents bit masks. A positive value indicates the number of file descriptors for which poll() has set the revents bit mask. If poll() fails, it returns -1 and sets errno to indicate the error.

ERRORS

poll() fails if any of the following conditions are encountered:

EAGAIN

Allocation of internal data structures failed. A later call to poll() may complete successfully.

EINTR

A signal was delivered before any of the selected for conditions occurred or before the time limit expired.

EINVAL

One of the following conditions is true:

timeout is a negative number other than -1.
The nfds argument is less than 0, greater than maxfiles, or greater than or equal to MAXFUPLIM. The kernel parameter maxfiles specifies the maximum number of file descriptors per process (see maxfiles(5)). MAXFUPLIM specifies the maximum number of files a process can have open at one time; it has a value of 2048 if the resource limit RLIMIT_NOFILE for a process is less than or equal to 2048.
One of the specified file descriptor refers to a stream or mux that is linked downstream from a mux.

EFAULT

The fds parameter in conjunction with the nfds parameter addresses a location outside of the allocated address space of the process. Reliable detection of this error is implementation-dependent.

EXAMPLES

Wait for input on file descriptor 0:

#include <poll.h> 
struct pollfd fds; 

fds.fd = 0; 
fds.events = POLLNORM; 
poll(&fds, 1, -1); 

Wait for input on ifd1 and ifd2, output on ofd, giving up after 10 seconds:

#include <poll.h> 
struct pollfd fds[3]; 
int ifd1, ifd2, ofd, count; 

fds[0].fd = ifd1; 
fds[0].events = POLLNORM; 
fds[1].fd = ifd2; 
fds[1].events = POLLNORM; 
fds[2].fd = ofd; 
fds[2].events = POLLOUT; 
count = poll(fds, 3, 10000); 
if (count == -1) { 
        perror("poll failed"); 
        exit(1); 
} 
if (count==0) 
        printf("No data for reading or writing\n"); 
if (fds[0].revents & POLLNORM) 
        printf("There is data for reading fd %d\n", fds[0].fd); 
if (fds[1].revents & POLLNORM) 
        printf("There is data for reading fd %d\n", fds[1].fd); 
if (fds[2].revents & POLLOUT) 
        printf("There is room to write on fd %d\n", fds[2].fd); 

Check for input or output on file descriptor 5 without waiting:

#include <poll.h> 
struct pollfd fds; 

fds.fd = 5; 
fds.events = POLLNORM|POLLOUT; 
poll(&fds, 1, 0); 
if (fds.revents & POLLNORM) 
        printf("There is data available on fd %d\n", fds.fd); 
if (fds.revents & POLLOUT) 
        printf("There is room to write on fd %d\n", fds.fd); 

Wait 3.5 seconds:

#include <stdio.h> 
#include <poll.h> 

poll((struct pollfd *) NULL, 0, 3500); 

Wait for a high priority, priority, or normal message on streams file descriptor 0:

#include <poll.h> 
struct pollfd fds; 

fds.fd = 0; 
fds.events = POLLIN|POLLPRI; 
poll(&fds, 1, -1); 

STANDARDS CONFORMANCE

poll(): AES, SVID2, SVID3

poll(2)

Technical documentation

» Table of Contents

» Index