Manpage of M_PCTTY

M_PCTTY

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

NAME

M_PCTTY - STREAMS interrupt message

FORMAT

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

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

INTERFACE

STREAMS, implementation extension.

DESCRIPTION

The M_PCTTY message is a high priority message type used for communication between the ldterm(4) module and the Stream head under AIX®[1]. Used by the AIX® Stream head to inform the ldterm(4) module when an event, such as read(2s) or ioctl(2s) has been aborted by user signal (timer or break). The ldterm(4) module must remove message blocks representing aborted read or ioctl from the queue and free it. A pointer to the original message block that was aborted is included in this message.

Any module or driver that can defer procesing on an M_IOCTL(9) or M_READ(9) message (a TCSETAW input-output control, for example) must be prepared to release that deferred message when the associated system call is interrupted. A typical scenario is as follows:

1.: An application starts a short duration timer.
2.: The application issues a "wait for drain" input-output control which takes some time to complete.
3.: The timer expires, interrupting the "wait for drain" input-output control.
4.: The application loops back up to restart the timer and reissue the input-output control, repeating this loop until most of the system memory is used by M_IOCTL(9) messages.

To prevent this situation, each time a read(2s) or ioctl(2s) system call is interrupted, the AIX® Stream head sends a M_PCTTY message downstream with a pointer to the message block associated with the interrupted system call. Any module or driver must compare that pointer to any queued message block and release the message block it it matches.

The M_PCTTY message will be formatted as a ttyblk structure, defined in the <sys/stream.h> header file. The tty_op field corresponds tot he tyupe of system call interrupted: either S_IOCTLGONE or S_READGONE. The b_rptr field of the message block contains the address of the message block to be released. Example code is as follows:

switch (mp->b_datap->db_type) {
case M_PCTTY:
    tb = (struct ttyblk *) mp->b_rptr;
    switch (tb->tty_op) {
    case S_IOCTLGONE:
        mp->b_rptr += sizeof(struct ttyblk);
        if (tp->t_qioctl == *((mblk_t **) mp->b_rptr)) {
            rmvq(q, tp->t_qioctl);
            freemsg(tp->t_qioctl);
            tp->t_qioctl = NULL;
            freemsg(mp);
            qenable(q);
        } else
            putnext(q, mp);
    }
}

A module that is pushed above the ldterm(4) module and processes M_DATA(9) messages received from the ldterm(4) module should send an M_READ(9) message downstream to the ldterm(4) module if more data is required. The ldterm(4) module only sends M_DATA(9) message upstream when an M_READ(9) is outstanding, so the pushed module must simulate the interaction between the Stream head and the ldterm(4) module. This module should also be prepared to receive an M_PCTTY message from the Stream head, indicating the termination of an outstanding read.

M_PCTTY messages are generated by the Stream head. M_PCTTY messages cannot be generated directly by a user level process (but indirectly upon receipt of a signal). M_PCTTY messages arriving at the Stream head are discarded (ignored and freed). M_PCTTY messages should not be geenrated by drivers or modules. M_PCTTY messages are consumed by the driver or module responding to them.

USAGE

This message is supposedly necessary because an indefinite number of M_IOCTL(9) or M_READ(9) messages could be otherwise queued. This is hard to support and probably just reflects a poorly designed ldterm(4) module. Only one (unabandonned) M_IOCTL(9) message can be outstanding at a time. The following put procedure code would do the same function as that above:

switch (mp->b_datap->db_type) {
case M_IOCTL:
    if (tp->t_qioctl != NULL) {
        rmvq(q, tp->t_qioctl);
        freemsg(tp->t_quioctl);
        tp->t_qioctl = mp;
    }
    putq(q, mp);
}

Although multiple M_READ(9) messages can be outstanding, the messages never need to be queued as they simply contain a count. (Note also that M_READ(9) messages are high priority messages.

NOTICES

The M_PCSETOPTS message is documented only by AIX®[1]. It is provided to assist porting of drivers and modules written for AIX® to Linux. It might be necessary to define _AIX_SOURCE before including <sys/stream.h> to expose this symbol. Binary compatibility is not guaranteed.

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

*: If an intermediate module recognizes, but is not deferring M_IOCTL(9) or M_READ(9) messages, it passes it downstream. As a high priority message, M_PCTTY messages are not subject to flow control and should not be queued.
*: If an intermediate module does not recognize the M_PCTTY message, it passes it along the Stream 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_PCTTY message and does not recognize the message, it is discarded (ignored and freed). If the driver is not deferring M_IOCTL(9) or M_READ(9) messages, the message is discarded (ignored and freed).
*: If an intermediate module or the driver recognizes the M_PCTTY mesage and is deferring M_IOCTL(9) or M_READ(9) messages, it treats the message as an indication that the deferred M_IOCTL(9) or M_READ(9) message belongs to an aborted attempt and consumes the message.

COMPATIBILITY

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

---: Only AIX®[1] documents the M_PCTTY data block type. This data block type is provided for source compatibility with drivers written for AIX® and should not be used by portable STREAMS drivers and modules. It might be necessary to define _AIX_SOURCE before including <sys/stream.h> to expost this symbol.
: Portable STREAMS modules and drivers will not use the M_PCTTY data block type.
---: The Linux Fast-STREAMS Stream head never generates one of these messages.
: Portable STREAMS modules and drivers will not use this message.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

AIX® documentation[1].

HISTORY

The M_TRAIL message first appeared in AIX®[1].

REFERENCES

[1]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>

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: 01:01:23 GMT, May 23, 2013