poll() provides applications with a mechanism for multiplexing input/output over a set of open file descriptors.
For each field element to which fds points, poll() checks whether one or more of the events listed in events has occurred for the corresponding file descriptor. The number of pollfd structures in the fds field is specified by the value nfds. poll() identifies the file descriptors which the application can read from or write to, or for which events have occurred.
fds defines the file descriptors to be checked as well as the events that are to be polled for the respective file descriptors. fds is a pointer to a field with one element each for every file descriptor to be checked. The elements of the field are pollfd structures, which contain the following:
int fd; /* Open file descriptor */
short events; /* Events to be queried */
short revents; /* Events that have occurred */
fd identifies an open file descriptor, events and revents are bit masks which are formed from the following flags through bitwise ORing (any combinations are possible):
POLLIN
| Data which does not have the highest priority can be read without blocking. For STREAMS this flag is set in revents even if the message has the length 0. |
POLLRDNORM
| Normal data (priority = 0) can be read without blocking. For STREAMS this flag is set in revents even if the message has the length 0. |
POLLRDBAND
| Data with priority != 0 can be read without blocking. For STREAMS this flag is set in revents even if the message has the length 0. |
POLLPRI
| Data with the highest priority can be received without blocking. For STREAMS this flag is set in revents even if the message has the length 0. |
POLLOUT
| Normal data (priority = 0) can be written without blocking. |
POLLWRNORM
| As POLLOUT. |
POLLWRBAND
| Data with priority != 0 can be written. |
POLLMSG
| An M_SIG or M_PCSIG message containing an ASIGPOLL signal has arrived at the beginning of the stream head queue. |
POLLERR
| An error has occurred for the STREAM or the special file. This flag is only valid in the revents bit mask; in the events bit mask it is ignored. |
POLLHUP
| A hang-up has occurred in the STREAM (the connection to the device has been interrupted). POLLHUP and POLLOUT mutually exclude each other; data can never be written to a stream if a hang-up has occurred. However, the event and POLLIN or POLLRDNORM, POLLRDBAND or POLLPRI do not mutually exclude each other.
The POLLHUP flag is only valid in the revents bit mask; in the events bit mask it is ignored. |
POLLNVAL
| The specified fd value is invalid. This flag is only valid in the revents bit mask; in the events bit mask it is ignored. |
If the value in fd is less than zero, events is ignored, and revents is set to 0 for this field entry when poll() returns.
The results of the poll() query are displayed in the revents field in the pollfd structure. poll() first sets all bits in revents to zero. If one or more of the events queried in events has occurred, poll() sets the corresponding bits in revents. The bits for POLLHUP, POLLERR and POLLNVAL are automatically set in revents when the corresponding events occur; they do not need to be set in events.
If the check reveals that none of the events queried for the file descriptors has occurred, poll() waits at least timeout milliseconds for an event to occur for one of the specified file descriptors. On a machine which does not offer precision in milliseconds, timeout is rounded up to the next permissible value available in this system. If the value of timeout is 0, poll() returns immediately. If timeout has the value -1, poll() waits until one of the queried events occurs, or until the call is interrupted (blocking poll() call).
poll() is not affected by the O_NDELAY and O_NONBLOCK flags.
poll() supports text files, terminals, pseudoterminals, STREAMS-based files, FIFO files and pipes, sockets and XTI.
With text files, poll() always returns a TRUE for reading and writing.
