NAME

poll − Monitors conditions on multiple file descriptors

SYNOPSIS

#include <sys/poll.h>

int poll(
struct pollfd filedes[ ],
unsigned int nfds,
int timeout );

PARAMETERS

filedesPoints to an array of pollfd structures, one for each file descriptor of interest. 

nfdsSpecifies the number of pollfd structures in the filedes array. 

timeoutSpecifies the maximum length of time (in milliseconds) to wait for at least one of the specified events to occur. 

DESCRIPTION

The poll() function 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. 

Each pollfd structure includes the following members:

int fdThe file descriptor

short events
The requested conditions

short revents
The 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, the poll() function sets the associated revents member. 

The poll() function ignores any pollfd structure whose fd member is less than 0 (zero).  If the fd member of all pollfd structures is less than 0, the poll() function will return 0 and have no other results. 

poll() provides users with a mechanism for multiplexing input/output over a set of file descriptors that reference open streams.  poll() identifies those streams on which a user can send or receive messages, or on which certain events have occurred.  A user can receive messages using read() or getmsg() and can send messages using write() and putmsg().  Certain ioctl() calls, such as I_RECVFD and I_SENDFD [see streamio() ], can also be used to receive and send messages. 

Neither the O_NDELAY or O_NONBLOCK flag affects poll(). 

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

POLLERRAn error has occurred on the file descriptor. 

POLLERROnly valid in revents bitmask; it is not used in the events field. 

POLLHUPThe device has been disconnected. 

POLLHUPA hangup has occurred on the stream. It is mutually exclusive with POLLOUT, a stream can never be writable if a hangup occurred. 

POLLINA non-priority or file descriptor passing message (see I_RECVFD) is present on the stream head read queue.  This flag is set even if the message is of zero length.  In revents, this flag is mutually exclusive with POLLPRI. 

POLLNORMData may be read without blocking. 

POLLNVALThe value specified for fd is invalid. 

POLLOUTData may be written without blocking. 

POLLPRIA priority message is present on the stream head read queue.  This flag is set even if the message is of zero length.  In revents, this flag is mutually exclusive with POLLIN. 

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. 

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 the poll() function, 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, the poll() function will return 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, the poll() function 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 bitmasks. 

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

NOTES

For compatibility with BSD systems, the select() function is also supported. 

AES Support Level:
Trial use

RETURN VALUES

Upon successful completion, the poll() function returns a nonnegative value.  If the call returns 0 (zero), poll() has timed out and has not set any of the revents bitmasks.  A positive value indicates the number of file descriptors for which poll() has set the revents bitmask.  If the poll() function fails, -1 is returned and errno is set to indicate the error. 

ERRORS

If the poll() function fails, errno may be set to one of the following values:

[EAGAIN]Allocation of internal data structures failed.  A later call to the poll() function may complete successfully. 

[EINTR]A signal was caught during the poll() function and the signal handler was installed with an indication that functions are not to be restarted. 

[EINVAL]The timeout parameter is a negative number other than -1. 

[EFAULT]The filedes parameter in conjunction with the nfds parameter addresses a location outside of the allocated address space of the process. 

RELATED INFORMATION

Functions: getmsg(2), putmsg(2), read(2), write(2), streamio(7).