Manpage of M_DATA

M_DATA

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

M_DATA - STREAMS data message

FORMAT

The M_DATA message block is a datab(9) structure and associated data buffer that contains unstructured data. (With a few exceptions, any structure imposed on the M_DATA data buffer is defined outside of STREAMS.)

An M_DATA message is a normal priority message that consists of one or more M_DATA message blocks.

INTERFACE

STREAMS.

DESCRIPTION

The M_DATA message is intended to contain ordinary data. Messages allocated by the allocb(9) utility are type M_DATA by default. M_DATA messages are generally sent upstream or downstream on a Stream and their contents can be passed between a process and the Stream head.

An M_DATA message consists of one or more M_DATA blocks. M_DATA messages are generally sent in both the downstream and upstream directions on a Stream. M_DATA message sent upstream and arriving at the Stream head are available to be read by user level processes using the read(2s), getmsg(2), or getpmsg(2s) system calls. M_DATA messages can be sent downstream from the Stream head by a user level process using the write(2s), putmsg(2), or putpmsg(2s) system calls.

When describing STREAMS-specific system calls, the contents of an M_DATA messsage are referred to collectively as the data part. For the getmsg(2), getpmsg(2s), putmsg(2), and putpmsg(2s) system calls, the control and data parts are passed separately. Only a putmsg(2) or putpmsg(2s) call that does not contain a control part will generate M_DATA messages. (For the messages resulting from calls to these system calls with a control part specified, see M_PROTO(9) and M_PCPROTO(9).) For the read(2s) and write(2s) system calls, only the data part is passed.

M_DATA messages can be formulated using multiple M_DATA message blocks. The minimum and maximum packet sizes associated with the upstream module read-side queue (that is, the q_minpsz and q_maxpsz fields of the upstream queue(9) structure), provide advise to the module on the minimum and maximum amounts of data that a given M_DATA block in an M_DATA message should contain. The Stream head will compact multiple M_DATA blocks into a single data part, when passing them to the user process. The write(2s), putmsg(2), and putpmsg(2s) system calls use the q_minpsz and q_maxpsz fields of the write-side queue of the topmost downstream module when determining the size and number of M_DATA blocks placed in the resulting downstream M_DATA messages. For a description of this procedure, see write(2s).

M_DATA messages, by nature of the initial message block type, are normal (or priority) messages, and are, therefore, subject to flow control restrictions with a Stream. In contrast, the non-standard M_HPDATA(9) message is a high priority message serving the same purpose, that is not subject to flow control restrictions. M_DATA messages can have an assigned priority. The priorty of an M_DATA message contained in the b_band member of the msgb(9) structure of the initial M_DATA message block in the message.

M_DATA messages passed upstream to be read by a user level process, or passed downstream as a result of being written by a user level process can support both a byte-stream view of the data path, where there are no message boundaries, or a packet (delimited) view, where message boundaries are preserved. To support the delimited view, M_DATA message blocks can optionally contain the MSGDELIM flag in the b_flag member of the intial message block to indicate that the last byte of the message represents a message boundary. A driver or module can request that the Stream head support the delimited view of M_DATA messages using the MSGDELIM flag, by sending an M_SETOPTS(9) message to the Stream head with the SO_DELIM flag set. For details, see SO_DELIM in M_SETOPTS(9), read(2s) and write(2s). Because a driver or module has no mechanism to examine Stream head options (only a mechanism to set them), drivers and modules should both generate and respect the MSGDELIM flag in M_DATA messages when appropriate.

Messages composed of multiple message blocks will typically have M_DATA as the message type for all message blocks following the first. Examples are M_PROTO(9), M_PCPROTO(9), M_IOCTL(9), M_IOCDATA(9), and M_CTL(9), messages. In the getmsg(2), getpmsg(2s), putmsg(2), and putpmsg(2s) system calls, the contents of the M_DATA message blocks, when attached to a M_PROTO(9) or M_PCPROTO(9) initial message block, are also referred to as the data part. Rules governing the creation and form of M_DATA messages also applies to the M_DATA(9) blocks attached to M_PROTO(9) and M_PCPROTO(9) messages. See M_PROTO(9) and M_PCPROTO(9) for details. M_DATA messages can be generated by user level processes using the write(2s), putmsg(2), putpmsg(2s), and I_INSERTFD(7) ioctl(2s) system calls. M_DATA message arriving at the Stream head are made available to the user level process for reading with read(2s), getmsg(2), getpmsg(2s) and I_PEEK(7) ioctl(2s) system calls. M_DATA messages may be generated by drivers and modules.

USAGE

M_DATA, M_PROTO(9) and M_PCPROTO(9) messages are the work horses of a service interface under STREAMS. They are generated both by user level processes as well as drivers and modules. These messages normally represent a default service primitive within a service interface definition at a message passing boundary within a Stream. An M_DATA message is normally equivalent to a M_PROTO(9) message, but with default control information associated with the message. The M_DATA message contains unstructured service interface user data.

COMPATIBILITY

The M_DATA STREAMS message is compatible with SVR 4.2 MP STREAMS, and implementations based on SVR 4, with the following portability considerations:

---: The M_DATA message is standard across STREAMS implementations, and has no portability issues.
---: Binary compatibiltiy is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[1].

HISTORY

The M_DATA message first appeared in SVR 3[2].

REFERENCES

[1]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

This document was created by man2html, using the manual pages.
Time: 17:32:49 GMT, May 22, 2013