STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Polling Streams
Chapter 2
33
Events Notified by poll(2)
STREAMS supports the following events requests in the poll (2) function:
POLLIN A non-high priority message, This is a a regular message or a priority band message at the
front of the stream head read-queue.
POLLNORM Same as POLLIN.
POLLPRI A high priority message is at the front of the stream head read queue.
POLLOUT A normal or priority band message can be written to the stream without being blocked by
flow control. This flag is not used for high priority messages — they can be set even when
the stream is under flow control.
POLLERR An error has occurred on the file descriptor. The errno value is appropriately set.
POLLHUP Stream hangup. This stream cannot have any more messages written to it.
NOTE POLLHUP and POLLOUT are mutually exclusive.
POLLNVAL The fd for this read queue is not a valid STREAMS file descriptor.
POLLRDNORM A normal (non-priority) message is at the front of the stream head read queue.
POLLRDBAND A priority band message is at the front of the stream head read queue.
POLLWRNORM Same as POLLOUT.
POLLWRBAND A priority band message can be written to the stream with no flow control restrictions.
POLLMSG An M_SIG or M_PCSIG message containing the SIGPOLL signal has reached the front of
stream head read queue.
Return Values
The poll (2) function examines each read queue for the occurrence of one or more of the corresponding events
specified by the events parameter. It returns to the calling application under one of the following conditions:
• At least one of the specified events occurs on at least one read queue
• The wait period reaches the timeout value
Upon return, the
revents parameter for each read-queue (corresponding to each fd in the pollfd array)
contains the corresponding events encountered on that read queue.
In addition to the
revents parameter, poll (2) returns a zero or a positive number indicating the number of
file descriptors (the number of stream head read queues) that contain at least one of the requested events,
within the specified timeout period. A return value of 0 indicates that none of the read-queues had any of the
requested events before the timeout value was reached. A return value of -1 indicates internal failure, and
causes errno to be set appropriately.
Important Aspects of poll(2) Functionality
• Three events (POLLERR, POLLHUP, and POLLNVAL) will be reported in the
revents parameter if and when
they are encountered. These events are reported even if they are not specifically requested in the poll (2)
call.
•The poll (2) ignores all negative file descriptors. This feature is relevant from a performance standpoint.
STREAMS applications that deal with multiple streams are likely to define a large array of pollfd
structures. The large array accommodates the maximum number of streams to be opened for the life of