Manpage of M_READ

M_READ

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

NAME

M_READ - STREAMS read message

FORMAT

The M_READ message block is a datab(9) structure and associated data buffer that contains structured data.

An M_READ message is a high priority message that consists of a single M_READ message block.

The M_READ message block contains a single unsigned long value reflecting the nbytes argument to the read(2s) system call.

INTERFACE

STREAMS.

DESCRIPTION

The M_READ message, (when requested using the SO_MREADON flag in a M_SETOPTS(9) message to the Stream head), is generated by the Stream head just prior to blocking a process calling read(2s), getmsg(2), or getpmsg(2s) that has opened the Stream for blocking operation (i.e., neither O_NONBLOCK nor O_NDELAY flags are set with open(2s) or fcntl(2)) due to an empty read queue at the Stream head.

By default, Stream heads do no generate M_READ messages: the SO_MREADON flag in the so_flags field of an M_SETOPTS(9) message must be sent to the Stream head by a driver or module to enable the generation of M_READ messages. Generation of M_READ messages can be disabled again using the SO_MREADOFF flag.

The format of the M_READ message is a single M_READ message block containing the unsigned long value of the nbyte argument to the read(2s) system call that generated the M_READ message. For the getmsg(2) or getpmsg(2) system calls where the data part is being retrieved, the unsigned long value in the M_READ message corresponds to the maxlen member of the strbuf(5) structure to which a pointer is passed in the datap argument to the getmsg(2) or getpmsg(2s) call.

M_READ messages, when enabled, notify drivers and modules of the occurence of a read that blocks. It is also intended to support communication between Streams that are hosted on separate processors.

The use of the resulting M_READ messages by drivers and modules is developer dependent. When processed, treatment of M_READ messages form part of the specification of the service interface.

M_READ messages cannot be generated directly by a user level process (but indirectly by performing a read operation). M_READ messages arriving at the Stream head are discarded (ignored and freed). M_READ messages should not be generated by drivers or modules. M_READ messages are consumed by the driver or module responding to them.

USAGE

For a STREAMS-based terminal in canonical mode, if the ICANON flag is on in c_lflag, canonical processing is performed. If the ICANON flag is off, non-canonical processing is performed (see termios(7) for more details). Handling of VMIN/VTIME in the STREAMS environment is somewhat complicated, because read(2s) needs to activate a timer in the ldterm(4) module in some cases; hence, read notification becomes necessary. When a user issues an ioctl(2s) to put ldterm(4) in non-canonical (raw) mode, the ldterm(4) module sends an M_SETOPTS(9) message to the Stream head to register read notification. Further reads on the terminal file descriptor will cause the Stream head to issue an M_READ message downstream and data will be sent upstream in response to the M_READ message. With read notification, buffering of raw data is performed by ldterm(4). It is possible to canonize the raw data, when the user has switched from raw to canonical mode. However, the reverse is not possible.

To summarize, in non-canonical mode, the ldterm(4) module buffers all data until a request for the data arrives in the form of an M_READ message. The number of bytes sent upstream will be the argument of the M_READ message. If the number is FASTBUF or less, the M_READ message can trasformed into an M_DATA(9) message to pass the data.

The following guidelines are for processing of the M_READ message at drivers and modules:

*: If an intermediate module recognizes, but is not processing the M_READ message, it passes it downstream. As a high priority message, the M_READ message is not subject to flow control and should not be queued.
*: If an intermediate module does not recognize the M_READ message, it passes it upstream or downstream as with any unrecognized high priority message: it is not subject to flow control and should not be queued.
*: If a driver receives an M_READ message and does not recognize the message, it is discarded. If the driver is not processing read notifications, the message is discarded.
*: If an intermediate module or the driver recognizes the M_READ message and is processing the message, it treats the message as an indication that a read attempt has been made that is blocked at the Stream head and consumes the message.

COMPATIBILITY

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

---: M_READ has a different constant value on OSF/1®[1], HP-UX®[2], MacOT®[3], and older versions of LiS[4].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[5] instead of LiS[4].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[6].

HISTORY

The M_READ message first appeared in SVR 3[7].

REFERENCES

[1]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[2]: HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>
[3]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>
[4]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[6]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[7]: 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: 06:45:28 GMT, May 22, 2013