STREAMS-UX Programmer's Guide (February 2007)

Message Types
High Priority Messages
Appendix C
247
M_COPYOUT
The M_COPYOUT message is generated by modules or drivers to request a copyout() to be performed on their
behalf by stream head. This message is valid only after receiving the M_IOCTL message by a module or driver
and before an M_IOCACK or M_IOCNAK message is sent upstream by a module or driver. The format of a
M_COPYOUT message is one message block of M_COPYOUT linked to one more M_DATA blocks containing data to
be copied to the user’s buffer. The data buffer in an M_COPYOUT message also contains a copyreq structure
with the following differences:
•The cq_ad refers to the address of the buffer from which data needs to be copied out for an M_COPYOUT
request.
•The cq_size specifies the number of bytes to be copied to the user space.
Data to be copied to the user space is contained in the linked M_DATA blocks. This message should not be
queued by a module or driver unless it intends to process the data for the IOCTL in some way.
M_ERROR
This message is sent upstream by modules and drivers to report downstream error conditions. Upon receiving
this message, the stream head does the following:
• Marks the stream in error state so that all subsequent system calls issued to the stream will fail (except
the close (2) and poll (2) system calls).
•Sets errno to the first byte of the message. The POLLERR is set if the stream is being polled (see poll (2)).
• Awakens all processes sleeping on a system call to the stream.
•Sends an M_FLUSH message downstream with FLUSHRW set.
The stream head maintains an error field for the read-side and one for the write-side. The M_ERROR message
could be in the one-byte or two-byte format. The one-byte format M_ERROR message sets both of the stream
head error fields to the error specified by the first byte in the message. In the two-byte format, the first byte is
used to set the read-side error and the second-byte is used to set the write-side error. If NOERROR is set in any
of the two-bytes, the corresponding side of the stream is unchanged. This provides flexibility to modules and
drivers to set different errors on the read-side and write-side, or set the error on only one side of the stream. If
a byte is set to 0, the error state is cleared for the corresponding side of a stream. The values, NOERROR and 0
are not valid for the one-byte format of the M_ERROR message.
M_FLUSH
This message requests all modules and drivers that receive this message, to discard all messages in their
corresponding message queues. An M_FLUSH can be sent by the stream head, or any module or driver. The first
byte of the message contains flag bits that specifies the queues to be flushed. The flags bits are:
FLUSHR: Flush the read queue of the module.
FLUSHW: Flush the write queue of the module.
FLUSHRW: Flush both the read queue and the write queue of the module.
FLUSHBAND: Flush the message according to the priority associated with the band.
When a module receives an M_FLUSH message, it flushes appropriate queues and passes the message to the
next stream component.
When a driver receives an M_FLUSH message, it does the following:
•If only FLUSHW is set, it flushes the write-queue and frees the message.