STREAMS Programming Guide

Message Handling

Since messages are the communication medium between the user application process and the various components of the Stream, this chapter describes the path they travel and the changes that occur to them. Chapter 8, Messages - Kernel Level covers the underlying mechanics of the kernel.

Modifying Messages

The put(9E) and srv(9E) interfaces process messages as they pass through the queue. Messages are generally processed by type, resulting in a modified message, one or more new messages, or no message at all. The message usually continues in the same direction it was passing through the queue, but can be sent in either direction. A put(9E) procedure can place messages on its queue as they arrive, for later processing by the service procedure. For a more detailed explanation of put and service, see Chapter 8, Messages - Kernel Level.

Some kernel operations are explained here to show you how to manipulate the driver or module appropriately.

Message Types

STREAMS messages differ according to their intended purpose and their queueing priority. The contents of certain message types can be transferred between a process and a Stream using system calls. Appendix A, Message Types describes message types in detail.

Control of Stream-Head Processing

The Stream-head responds to a message by altering the processing associated with certain system calls. Six Stream-head characteristics can be modified. Four characteristics correspond to fields contained in queue (packet sizes -- minimum and maximum, and watermarks -- high and low. Packet sizes are discussed in this chapter. Watermarks are discussed in "Flush Handling" in Chapter 4, STREAMS Driver and Module Interfaces.

Read Options

The value of read options (so_readopt) specifies two sets of three modes that can be set by the I_SRDOPT ioctl(2) (see streamio(7I)).

Byte-stream mode approximately models pipe data transfer. Message nondiscard mode is similar to a TTY in canonical mode.

Table 3-1 Read Option Modes













The first set of bits, RMODEMASK, deals with data and message boundaries, as shown in Table 3-1.

byte-stream (RNORM)

The read(2) call finishes when the byte count is satisfied, the Stream-head read queue becomes empty, or a zero length message is encountered. A zero-length message is put back in the queue. A subsequent read returns 0 bytes.

message non-discard (RMSGN)

The read(2) call finishes when the byte count is satisfied or a message boundary is found, whichever comes first. Any data remaining in the message is put back on the Stream-head read queue.

message discard (RMSGD)

The read(2) call finishes when the byte count is satisfied or a message boundary is found. Any data remaining in the message is discarded up to the message boundary.

The second set of bits, RPROTMASK, specifies the treatment of protocol messages by the read(2) system call:

normal protocol (RPROTNORM)

The read(2) call fails with EBADMSG if an M_PROTO or M_PCPROTO message is at the front of the Stream-head read queue. This is the default operation protocol.

protocol discard (RPROTDIS)

The read(2) call discards any M_PROTO or M_PCPROTO blocks in a message, delivering the M_DATA blocks to the user.

protocol data (RPROTDAT)

The read(2) call converts the M_PROTO and M_PCPROTO message blocks to M_DATA blocks, treating the entire message as data.

Write Options

send zero (I_SWROPT)

The write(2) mode is set using the value of the argument arg. Legal bit settings for arg are: SNDZERO--Send a zero-length message downstream when the write of 0 bytes occurs. To avoid sending a zero-length message when a write of 0 bytes occurs, this bit must not be set in arg. On failure, errno can be set to EINVAL--arg is above the legal value.