STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Asynchronous Event Notification
Chapter 2
38
Asynchronous Event Notification
The polling method described in the previous section is synchronous. The application has to explicitly stop
what it is doing, and poll each time it needs to check the occurrence of relevant events on different file
descriptors.
Asynchronous Event Notification enables the user to set the event conditions in advance, and then continue
with its normal operations until interrupted by the occurrence of one of those event conditions. The I_SETSIG
ioctl (2) command enables user applications to specify one or more events for a stream.
The IOCTL Command — I_SETSIG
Synopsis
#include <sys/types.h>
#include <sys/stropts.h>
int ioctl(int fd, I_SETSIG, *arg);
I_SETSIG is the command used for setting a bit-mask of relevant events. It directs the kernel routines
associated with the stream head to issue a SIGPOLL signal upon the occurrence of any of the selected events.
The
arg parameter is a bitmask that specifies events that will signal an interrupt to the calling application. It
is the bitwise-OR of any combination, except where noted, of the events listed here. For more information and
a complete list of IOCTL commands, refer to Appendix A, “STREAMS IOCTL Commands.”
S_ERROR An M_ERROR message has reached the stream head.
S_HANGUP An M_HANGUP message has reached the stream head.
S_HIPRI A high priority message is present on the stream head read queue.
S_INPUT A message other than an M_PCPROTO has arrived on a stream head This argument is
maintained for compatibility with prior UNIX System V releases. This argument is set even
if the message is of zero length.
S_MSG A STREAMS signal message containing the SIGPOLL signal has reached the front of the
stream head read queue.
S_OUTPUT The write-queue just below the stream head is no longer full.
S_RDBAND A priority band message has arrived at the stream head read queue. This is set even if the
message is of zero length.
S_BANDURG When used in conjunction with S_RDBAND, a SIGURG is generated instead of SIGPOLL when a
priority message reaches the front of the stream head read queue.
S_RDNORM An ordinary (normal) message has arrived at the stream head read queue. This is set even if
the message is of zero length.
S_WRBAND A priority band greater than zero of a queue downstream exists and is writable. This
notifies the user that there is room on the queue for sending priority data downstream.
S_WRNORM Same as S_OUTPUT.
An
arg parameter value of zero can be used to deregister the I_SETSIG events set by a previous ioctl call.
Following an I_SETSIG setup, the stream head generates a SIGPOLL signal for the user application when
relevant events occur. It is the responsibility of the user application to appropriately handle this signal. A
typical setup for signal handling is: