STREAMS-UX Programmer's Guide (February 2007)

Message Types
High Priority Messages
Appendix C
248
•If FLUSHR or FUSHRW is set, it flushes the read-queue, clears the FLUSHW flag and sends the message
upstream.
When a stream head receives an M_FLUSH message, it does the following:
•If only FLUSHR is set, it flushes the read-queue and frees the message.
•If FLUSHW or FLUSHRW is set, it flushes the write-queue, turns the M_FLUSH message around, and sends it
downstream.
If FLUSHBAND is set, the second byte of the M_FLUSH data buffer contains the band priority value. In this case,
the flush flags apply only to the specified priority band.
NOTE All modules that enqueue messages must identify and process M_FLUSH messages.
M_HANGUP
This message is generated and sent upstream by a driver to indicate that the driver can no longer send data
upstream. The reasons for generating this message are driver and device-dependent. For example, it could be
an unrecoverable error or a remote line connection being dropped.
If a M_TRAIL message is used to mark the end of data after the M_HANGUP message, then the M_HANGUP
message must contain the 2-byte TRAIL_TOKEN defined in <sys/stream.h>.
When the stream head receives a M_HANGUP message, it marks the stream in the hangup state, and all
subsequent write() and putmsg() system calls issued to that stream will fail with an ENXIO error. Also,
IOCTL commands requiring a message to be sent downstream will fail. The POLLHUP will be set if the stream
is being polled (see poll (2)).
However, subsequent read() or getmsg() calls to the stream will not generate an error. These calls will
return any messages that were in, or in transit to, the stream head read-queue before the M_HANGUP message
was received. When all such messages have been read, read() will return 0 and getmsg() will set each of its
two length fields to 0.
This message also causes a SIGHUP signal to be sent to the foreground process group if the device is a
controlling terminal.
M_IOCACK
This message is used by modules and drivers to send a positive acknowledgment in response to an M_IOCTL
message. The M_IOCACK message format is one M_IOCACK block (containing iocblk structure, see M_IOCTL)
followed by zero or more M_DATA blocks. The ioc_rval field of the iocblk structure can be used to send
return values to user process. ioc_error can be used to communicate processing errors, if any, back to the
user in errno.
For M_IOCACK messages in response to I_STR IOCTL, the user data to be returned is formatted as an
M_IOCACK message block followed by one or more M_DATA blocks that contain user data. The stream head
returns the data to the user if there is a corresponding outstanding M_IOCTL request. Otherwise, the
M_IOCACK message is ignored and all blocks in the message are freed.
Data can not be returned in an M_IOCACK message in response to a transparent IOCTL request. The user data
to be returned for transparent IOCTL must be sent as M_COPYOUT messages. If any user data is linked as
M_DATA blocks to the M_IOCACK block, the stream head will ignore and free them.