Manpage of M_ERROR

M_ERROR

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

NAME

M_ERROR - STREAMS error message

FORMAT

The M_ERROR message block is a datab(9) structure and associated data buffer that contains structured data. The contents of the M_ERROR message block is zero, one, or two character width integer error numbers.

An M_ERROR message is a high priority message that consists of one M_ERROR message block.

INTERFACE

STREAMS.

DESCRIPTION

The M_ERROR message is generated by a driver or module and sent upstream by drivers or modules to report some downstream error condition. When the message reaches the Stream head, the Stream is marked so that all subsequent system calls issued to the Stream, excluding close(2s) and poll(2s), will fail with errno(3) set to the first data byte of the message. POLLERR is set if the Stream is being polled [see poll(2s)]. All proceses sleeping on a system call to the Stream are awakened. An M_FLUSH(9) message with FLUSHRW is then sent downstream from the Stream head.

The Stream maintains two error fields, one for the read-side and one for the write-side. The, older, zero- and one-byte form M_ERROR message sets both of these fields to the error specified by the first byte in the message, or cleared the error when a zero-byte message arrived.

The second style of the M_ERROR message is two bytes long. The first byte is the read error and the second byte is the write error. This allows modules to set a different error on the read-side and write-side. If one of the bytes is set to NOERROR, then the field for the corresponding side of the Stream is unchanged. This allows a module to adjust an error on one side of the Stream. For example, if the Stream head was not in an error state and a module sent an M_ERROR message upstream with the first byte set to [EPROTO] and the second byte set to NOERROR, all subsequent write-like system calls (for example, write(2s), putmsg(2)) will still succeed: only read-like system calls (read(2s), getmsg(2)), will fail with errno(3) set to [EPROTO]. If a byte is set to zero (0), the error state is cleared for the corresponding side of the Stream. The values of NOERROR and zero (0) are not valid for the one-byte form of the M_ERROR message.

WHen this message type is received, the first byte of the message is put into the Stream head (sd_rerror) and the STRDERR flag is set; the second byte is placed in sd_werror and the STDWERR flag is set. If the error code in the message has a special value NOERROR, the corresponding flag is not set. However, if the error flag is set, a read(2s) or write(2s) will fail, and the value returned to the process in errno(3) is taken from sd_rerror or sd_werror. The error condition prevents all further reads and writes to the Stream util it is closed, or the Stream head receives a NOERROR code in an M_ERROR message. The relevant processes (all processes blocked on read or write, or blocked awaiting acknowledgement to an M_IOCTL(9) message, or that have registered to receive {SIGPOLL} for the S_ERROR event) are then awoken or signalled. Finally, a M_FLUSH(9) message is sent downstream to discard all data queued in the Stream. Note that many of the STREAMS system calls and streamio(7) IO controls block awaiting message arriving at the Stream head or flow control to subside on a message band. These system calls and streamio(7) IO controls describe what occurs in the event of the receipt of what is termed an asynchronouserror , that is, arrival at the Stream head of an M_ERROR(9) message.

The putctl(9), and putnextctl(9), STREAMS utility functions are useful for modules generating the zero-byte form of the message. The putctl1(9), and putnextctl1(9), STREAMS utility functions are useful for modules generating the one-byte form of the message. The putctl2(9), and putnextctl2(9) STREAMS utility functions were added in support of the newer two-byte error message. M_ERROR messages cannot be generated directly by user level processes. M_ERROR messages arriving at a non-multiplexing driver should be discarded (ignored and freed). M_ERROR messages can be generated by drivers and modules. M_ERROR messages are consumed by the Stream head.

USAGE

The following guidelines provide best practise for generation of the M_ERROR message for drivers and modules:

*: The M_ERROR message is a high priority message and is not subjected to flow control. Modules should pass the M_ERROR message along directly from a qi_putp(9) procedure and should not queue the message.
*: Modules and driver should only pass this message upstream. Intermediate modules may record the fact that a M_ERROR message has transitted the module, and the error numbers contained in the message; however, the module must pass the M_ERROR message along upstream.
*: An M_ERROR message arriving at the write-side queue of a module should be passed along as an unrecognized message type. This permits M_ERROR messages to be passed along a STREAMS-based pipe(4).
*: An M_ERROR message arriving at the write-side queue of a driver should be discarded.
*: An M_ERROR message arriving at the read-side queue on the lower side of a multiplexing driver should be treated in a similar fashion as the Stream head. That is, the driver should record the error numbers, cease (or resume) receiving or sending messages on the lower multiplexer queue pair and should flush the appropriate sides of the linked Stream.
*: Because of the asynchronous nature of the M_ERROR message and reporting of the error number values contained in it, use of the M_ERROR message by a driver or module should be reserved for fatal error conditions, where the Stream is unusable and will require the Stream to be dismantled and recreated to clear the error condition. Non-fatal error conditions should be reported within the protocol of the service interface.
*: Simple hangups are to be reported using the M_HANGUP(9) message and not an M_ERROR(9) message with the error number(s) set to [ENXIO].
*: M_ERROR should not be used to return an error to an ioctl(2s) system call. Unless a fatal error has truly occured, an M_IOCNAK(9) message should be used instead.
*: All new drivers and modules should use the two-byte form of the message. Existing STREAMS modules using the zero- and one-byte form, should be converted to use the two-byte form.

COMPATIBILITY

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

---: M_ERROR provide backwards compatibility of the newer two-byte format of the message with the older zero- and one-byte format of the message. If a zero-byte M_ERROR message is received by the Stream head, it is treated as equivalent to a two-byte message with both fields set to NOERROR. If a one-byte M_ERROR message is received by the Stream head, it is treated as equivalent to a two-byte message with both fields set to the error number in the single field of the received one-byte message.
: Portable STREAMS drivers and modules will only use the 2-byte form of the M_ERROR message.
---: Contrary to the description in TheMagicGarden ,[1] when a read error occurs, only the read-side of the Stream is flushed; a write error, the write-side; both errors, both sides.
: Portable STREAMS modules and driver should not expect the upstream queues to be flushed when only a write error occurse, nor the downstream queues flushed when a read error occurs.
---: M_ERROR is has the wrong message type value on older versions of LiS[2].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[3] instead of LiS[2].
---: Binary compatibiltiy is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[4].

HISTORY

The M_ERROR message first appeared in SVR 3[5]. The two-byte format for the M_ERROR message first appeared in SVR 4.2[4].

REFERENCES

[1]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[2]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[3]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[4]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[5]: 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: 10:55:06 GMT, May 21, 2013