HDK Technical Reference

Messages, STREAMS

STREAMS messages are the basic unit used for input and output to STREAMS devices. The objects passed between STREAMS modules are pointers to messages. All STREAMS messages use two data structures, msgb(D4str) and datab(D4str), to refer to the message data. These data structures describe the type of the message and contain pointers to the data of the message, as well as other information. Messages are sent through a Stream by successive calls to the put(D2str) procedure of each module or driver in the Stream.

This article provides background information about STREAMS messages. See ``Message block allocation'' for guidelines about allocating STREAMS message blocks.

Message types

All STREAMS messages are assigned message types to indicate their intended use by modules and drivers and to determine their handling by the Stream head. These message types are documented in Section D7str manual pages. A driver or module can assign most types to a message it generates, and a module can modify a message type during processing. The Stream head converts certain system calls to specified message types and sends them downstream. It responds to other calls by copying the contents of certain message types that were sent upstream.

Most message types are internal to STREAMS and can only be passed from one STREAMS component to another. A few message types (for example M_DATA(D7str), M_PROTO(D7str), and M_PCPROTO(D7str)) can also be passed between a Stream and user processes. M_DATA messages carry data within a Stream and between a Stream and a user process. M_PROTO or M_PCPROTO messages carry both data and control information.

The following illustration shows that a STREAMS message consists of one or more linked message blocks that are attached to the first message block of the same message.

A message

Messages can exist stand-alone, as in the previous illustration, when the message is being processed by a procedure. A message can also await processing on a linked list of messages, called a message queue. In the following illustration, Message 2 is linked to Message 1.

Messages on a message queue

When a message is on a queue, the first block of the message contains links to preceding and succeeding messages on the same message queue, in addition to the link to the second block of the message (if present). The message queue head and tail are contained in the queue.

STREAMS utility routines enable developers to manipulate messages and message queues.

Message queuing priority

In certain cases, messages containing urgent information (such as a break or alarm conditions) must pass through the Stream quickly. To accommodate these cases, STREAMS provides multiple classes of message queuing priority. All messages have an associated priority field. Normal (ordinary) messages have a priority of zero. Priority messages have a priority greater than zero. High-priority messages are high-priority by virtue of their message type. The priority field in high-priority messages is unused and should always be set to zero. STREAMS prevents high priority messages from being blocked by flow control and causes a srv( )
procedure to process them ahead of all ordinary messages on the queue. This results in the high priority message transiting each module with minimal delay.

Non-priority, ordinary messages are placed at the end of the queue following all other messages in the queue. Priority messages can be either high priority or priority band messages. High-priority messages are placed at the head of the queue but after any other high-priority messages already in the queue. Priority band messages that enable support of urgent, expedited data are placed in the queue after high-priority messages but before ordinary messages.

Message priority is defined by the message type; once a message is created, its priority cannot be changed. Certain message types come in equivalent high priority/ordinary pairs (for example, M_PCPROTO and M_PROTO), so that a module or device driver can choose between the two priorities when sending information.

© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005