Manpage of M_IOCDATA

M_IOCDATA

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

NAME

M_IOCDATA - STREAMS IO control data message

FORMAT

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

An M_IOCDATA message is a high priority message that consists of one M_IOCDATA message block followed by one or more M_DATA(9) message blocks.

INTERFACE

STREAMS.

DESCRIPTION

The M_IOCDATA message is generated by the Stream head and sent downstream as a response to an M_COPYIN(9) or M_COPYOUT(9) message. The message format is one M_IOCDATA message block followed by zero or more M_DATA(9) blocks. The M_IOCDATA message block contains a copyresp(9) structure, defined in <sys/stream.h>:

struct copyresp {
    int cp_cmd;         /* command being performed */
    cred_t *cp_cr;      /* credentials */
    uint cp_id;         /* id of this ioctl */
    caddr_t cp_rval;    /* result 0 - success, 1 - failure */
    uint cp_pad1;       /* reserved */
    int cp_pad2;        /* reserved */
    mblk_t *cp_private; /* private state information */
    long cp_filler[4];  /* SVR4 compatibility */
#define cp_flag cp_filler[0] /* IOC_NATIVE or IOC_ILP32 */
};
#define cp_uid cp_cr->cr_uid
#define cp_gid cp_cr->cr_gid
#define IOC_MASK   0xff000000 /* mask of model bits */
#define IOC_NONE   0x00000000 /* no indication */
#define IOC_NATIVE 0x01000000 /* native ioctl request */
#define IOC_ILP32  0x02000000 /* 32bit ioctl request */
#define IOC_LP64   0x03000000 /* 64bit ioctl request */

The first three members of the structure (cp_cmd, cp_cr, cp_id) correspond to those of the iocblk(9) structure in the M_IOCTL(9) message which allows the same message blocks to be reused for all of the related transparent messages (M_COPYIN(9), M_COPYOUT(9), M_IOCACK(9), M_IOCNAK(9)). The cp_rval field contains the result of the request at the Stream head. Zero ((caddr_t)(0)) indicates success and non-zero (typically (caddr_t)(1)) indicates failure. If failure is indicated, the module should not generate an M_IOCNAK(9) message. It must abort all ioctl(2s) processing, clean up its data structures, remove and free any message blocks linked to the cp_private member, free the M_IOCDATA message, and return.

The cp_private field is copied from the cq_private field in the associated M_COPYIN(9) or M_COPYOUT(9) message. It is included in the M_IOCDATA message so the message can be self-describing. This is intended to simplify ioctl(2s) processing by drivers and modules.

The cp_flag field is set by the Stream head and has the same value as the ioc_flag field in the original corresponding M_IOCTL(9) message. The cp_flag field can have the values as follows:

IOC_NONE: indicates that the M_IOCDATA message did not originate from the Stream head, but from an intermediate module or driver. No conversions are required on data.
IOC_NATIVE: indicates that the copyin(9) or copyout(9) operation was performed for a process with the same data model as the driver (i.e. LP64). No conversions are required on data copied in.
IOC_ILP32: indicates that the copyin(9) or copyout(9) operation was performed for a process with a different data model (31- or 32-bit) from the kernel (i.e. ILP32 instead of LP64). Conversion is required on data copied in.
IOC_LP64: indicates that the copyin(9) or copyout(9) operation was performed for a process with the same data model as the driver (i.e. LP64). No conversions are required on data copied in.

If the message is in response to an M_COPYIN(9) message and success is indicated, the M_IOCDATA block will be followed by M_DATA(9) blocks containing the data copied in. If an M_IOCDATA block is reused, any unused fields defined for the resultant message block should be cleared (particularly in an M_IOCACK or M_IOCNAK).

This message should not be queued by a driver or module unless it intends to process the data for the ioctl(2s) in some way. M_IOCDATA messages cannot be generated directly by a user level process. M_IOCDATA messages arriving at the Stream head are discarded (ignored and freed). M_IOCDATA messages are generated by the Stream head in response to received M_COPYIN(9) or M_COPYOUT(9) messages. M_IOCDATA messages must be consumed by the driver or module that issued the M_COPYIN(9) or M_COPYOUT(9) message.

USAGE

The guidelines for processing the M_IOCDATA message are as follows:

*: If a module receives an M_IOCDATA message to its write-side qi_putp(9) procedure, and the module is not processing an M_COPYIN(9) or M_COPYOUT(9) request, the module passes the M_IOCDATA downstream, directly from its qi_putp(9) procedure, with a call to putnext(9).
*: If a driver receives an M_IOCDATA message to its write-side qi_putp(9) procedure, and the driver is not processing an M_COPIN(9) or M_COPYOUT(9) request, the driver discards the M_IOCDATA message.
*: If a module receives an M_IOCDATA message to its read-side qi_putp(9) procedure, the module should either pass the message upstream using putnext(9) or discard the message.
*: Drivers should not generate M_IOCDATA messages upstream.
*: If an M_IOCDATA message is received at the Stream head, the message is discarded.
*: If a driver or module is processing an M_COPYIN(9) or M_COPYOUT(9) request, and an M_IOCDATA message is received to the write-side qi_putp(9) procedure, the driver or module must process the message, but may queue the message for processing out of the module's qi_srvp(9) procedure.
*: When processing the message the driver or module examines the cp_rval member of the contained copyresp(9) structure to determine if the operation was successful or not.
*: If not successful, all operations associated with the M_IOCTL(9) must be aborted and cleaned up. No M_IOCNAK(9) message is sent.
*: If successful and a M_COPYIN(9) request was being performed, M_DATA(9) blocks following the message contain the copied in data.
*: If successful and a M_COPYOUT(9) request was being performed, only success is indicated.
*: When successful, the driver or module may continue the M_IOCTL(9) operation with additional M_COPYIN(9) or M_COPYOUT(9) requests, or by concluding the M_IOCTL(9) operation with a M_IOCACK(9) or M_IOCNAK(9) acknowledgement.

COMPATIBILITY

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

---: Alignment of iocblk(9), copyreq(9), and copyresp(9), structures to each other and which members are overlaid over which other members, and what the differences are between the 32-bit architecture structures and the 64-bit architecture structures, is complicated and problematic among UNIX® implementations of STREAMS.
: Portable STREAMS drivers and modules will not rely upon the ordering or overlap of members within the copyresp(9) structure, and will only examine and modify members in accordance with the SVR 4 STREAMS Programmer's Guide[1].
---: The cp_flag field is documented only by Solaris®[2] with the same sematics as provided by Linux Fast-STREAMS as described above, for compatibility with Solaris®[2]. Nevertheless, the interpretation of the cp_flag is non-portable, and, as the cp_flag occupies one of the cp_filler elements in the SVR 4.2 structure, examining it on implementations other than Solaris®[2] or Linux Fast-STREAMS could have undefined results.
: Portable STREAMS drivers and modules will not examine the cp_flag field.
---: When a driver or module receives an M_IOCDATA indicating an error (cp_rval is non-zero), it is supposed to free any private resources associated with the ioctl(2s), abort the ioctl(2s) operation, free the message, and return[1]. When the Stream head sends such a message, it aborts the current M_IOCTL(9) operation and returns the error number to the user in errno(3) indicating the cause of failure of the operation. In the error case, the Stream head does not block awaiting any further ioctl(2s) message blocks, and release the STRIOWAIT bit in the Stream head.
: LiS[3] has the bug that it waits for a subsequent M_IOCACK(9) or M_IOCNAK(9) block. (Note however, that drivers and modules previously written to work with LiS[3] will also work with Linux Fast-STREAMS[4]; however, the extraneous M_IOCACK(9) or M_IOCNAK(9) will be discarded by the Stream head as the input-output control transaction has been closed, and the error number reported will be that of the failed copyin(9) or copyout(9) operation, i.e. [EFAULT], and not that contained in any M_IOCNAK(9) message.)
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[4] instead of LiS[3].
---: M_IOCDATA has a different constant value on HP-UX®[5], MacOT®[6], OSF/1®[7], and older versions of LiS[3].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[4] instead of LiS[3].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[8].

HISTORY

The M_IOCDATA message first appeared in SVR 3[9].

REFERENCES

[1]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[3]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[4]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: 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/>
[6]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>
[7]: 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/>
[8]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[9]: 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:09:35 GMT, May 21, 2013