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() examines 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 identifies 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.

POLLRDNORM

Normal data (priority band equals 0) may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.

POLLRDBAND

Data from a non-zero priority band may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.

POLLPRI

High-priority data may be received without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.

POLLOUT

Normal data (priority band equals 0) may be written without blocking.

POLLWRNORM

Same as POLLOUT.

POLLWRBAND

Priority data (priority band > 0) may be written. 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 is 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 is ignored in the events member.

POLLNVAL

The specified fd value is invalid. This flag is only valid in the revents member; it is ignored in the events member.

If the value of fd is less than 0, events is ignored and revents is set to 0 in that entry on return from poll().

In each pollfd structure, poll() clears 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() sets the corresponding bit in revents if the requested condition is true. In addition, poll() sets 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() waits at least timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of timeout is 0, poll() returns immediately. If the value of timeout is -1, poll() blocks 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 will be rounded up to the next supported value.

The poll() function is not affected by the O_NONBLOCK flag.

The poll() function supports regular files, terminal and pseudo-terminal devices, STREAMS-based files, FIFOs and pipes. The behaviour of poll() on elements of fds that refer to other types of file is unspecified.

Regular files always poll TRUE for reading and writing.

 RETURN VALUE

Upon successful completion, poll() returns 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() returns -1 and sets errno to indicate the error.

 ERRORS

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

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

getmsg(), putmsg(), read(), select(), write(), <poll.h>, <stropts.h>, STREAMS overview.