M_IOCACK

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

NAME

M_IOCACK - STREAMS IO control acknowledgement message

FORMAT

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

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

The M_IOCACK message block contains a iocblk(9) structure, formatted as follows:

struct iocblk {
    int ioc_cmd;        /* ioctl command type */
    cred_t *ioc_cr;     /* full credentials */
    uint ioc_id;        /* ioctl identifier */
    ulong ioc_count;    /* byte count for ioctl data */
    int ioc_error;      /* error code for M_IOCACK/NAK */
    int ioc_rval;       /* return value for M_IOCACK */
    long ioc_filler[4]; /* reserved for future use */
#define ioc_flag ioc_filler[1]; /* IOC_NATIVE or IOC_ILP32 */
};

where,

ioc_cmd: contains the corresponding command from the M_IOCTL(9) message block.
ioc_cr: contains the corresponding user credentials pointer from the M_IOCTL(9) message block.
ioc_id: contains the corresponding IO control identifier from the M_IOCTL(9) message block.
ioc_count: contains the count of the number of bytes to be copied to the user by the Stream head with copyout(9), contained in the attached M_DATA(9) message block(s).
ioc_error: contains the error number for the Stream head to return to the user in errno(3).
ioc_rval: contains the return value for the Stream head to return to the user on the ioctl(2s) system call that began the operation.
ioc_flag: is ignored by the Stream head in the M_IOCACK message.

INTERFACE

STREAMS.

DESCRIPTION

The M_IOCACK message is generated and sent from the driver or module processing an M_IOCTL(9) message. The M_IOCACK message signals to the Stream head the positive acknowlegment of the M_IOCTL(9) message and completion of the ioctl(2s) system call.

The message format is one M_IOCACK block (containing an iocblk(9) structure, see M_IOCTL(9)) followed by zero or more M_DATA(9) blocks. The iocblk(9) structure may contain a value in ioc_rval to be returned to the user process. It may also contain a value in ioc_error to be returned to the user process in errno(3).

If this message is responding to an I_STR(7) ioctl(2s) [see streamio(7)], it may contain data from the receiving driver or module to be copied to the user process by the Stream head with copyout(9). In this case, message format is one M_IOCACK block followed by one or more M_DATA(9) blocks containing the user data. The responding driver or module will set ioc_count to the number of bytes to be copied out from the attached M_DATA(9) message block(s).

The Stream head returns the data to the user if there is a corresponding outstanding M_IOCTL(9) request (that is, one with the same ioc_id). Otherwise, the M_IOCACK message is ignored and all blocks in the message are freed.

Data can not be returned in an M_IOCACK message responding to a transparent M_IOCTL(9). The data must have been sent with preceding M_COPYOUT(9) message(s). If any M_DATA(9) blocks follow the M_IOCACK block, the Stream head will ignore and free them. When the Stream head receives an M_IOCACK, the outstanding ioctl(2s) request, if any, will succeed.

The format and use of this message type is described further under M_IOCTL(9). M_IOCACK messages cannot be generated directly by a user level process. M_IOCACK messages arriving at a non-multiplexing driver can be discarded (ignored and freed). M_IOCACK message can be generated by drivers and modules responding to an M_IOCTL(9) message. M_IOCACK messages are consumed by the Stream head.

USAGE

Guidlines for procesing the M_IOCACK message are as follows:

*: Intermediate modules that do not intend to process this message will not queue the M_IOCACK message upstream. In any event, an intermediate module must not flush or discard an M_IOCACK message.
: As only one ioctl(2s) operation, and therefore, one M_IOCACK message can be in progress on a Stream, queueing of the message would cause unnecessary dealy in processing an ioctl(2s). Only one high-priority message can be outstanding at the Stream head, so ordering of this message with respect to other high priority messages is not an issue.
*: Modules or drivers should only issue a M_IOCACK message containing a ioc_count value in response to a non-tranparent ioctl(2s).
*: The message should be created by transforming a received M_IOCTL(9) or M_IOCDATA(9) message.
*: An intermediate module receiving an M_IOCACK message on its write-side queue, will pass the message along in the same manner as any unexpected high priority message: that is, it is passed to the next module and not subjected to flow control. This permits ioctl(2s) handling to perform correctly across a STREAMS-based pipe(4).
*: A driver receiving an M_IOCACK message discards the message.

NOTICES

Under Linux Fast-STREAMS[1] it is not possible to return an error and a return value at the same time. This is due to a Linux limitation in this regard.

COMPATIBILITY

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

---: The order and size of the various members of the iocblk(9) structure, and the associated aligned copyreq(9) and copyresp(9) structures, vary in STREAMS from implementation to implementation. Some implementations have different structure definitions depending upon the word size of a specific architecture. Linux Fast-STREAMS[1] follows the SVR 4.2 implementation as closely as possible.
: Portable STREAMS drivers and modules will not rely upon a specific overall size of the ioclk(9) structure, or the offset or alignment of any of its members. See iocblk(9) for additional compatibiltiy information.
---: M_IOCACK is has the wrong message type value on older versions of LiS[2].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[1] instead of LiS[2].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[3].

HISTORY

The M_IOCACK message first appeared in SVR 3[4].

REFERENCES

[1]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[3]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]: 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: 11:08:19 GMT, May 24, 2013

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci