Manpage of M_PASSFP

M_PASSFP

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Thu, 23 May 2013 14:31:47 GMT
Index Return to Main Contents

NAME

M_PASSFP - STREAMS pass file pointer message

FORMAT

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

An M_PASSFP message is a normal priority message that consists of a single M_PASSFP message block.

INTERFACE

STREAMS.

DESCRIPTION

The M_PASSFP message is used internally by STREAMS to pass a file pointer from the Stream head at one end of a STREAMS-based pipe(4) to the Stream head at the other end of the same STREAMS-based pipe(4).

The message is generated as a result of an I_SENDFD(7) command to an ioctl(2s) system call issued by a user level process to the sending Stream head. STREAMS places the M_PASSFP message directly on the destination Stream head's read queue to be retreived by an I_RECVFD(7) command to the ioctl(2s) system call. The message is placed without passing it through the Stream (i.e., it is not seen by any drivers or modules in the Stream). This message should never be present on any queue except the read queue of a Stream head. Consequently, drivers and modules do not need to recognize this message, and it can be ignored by driver and module developers.

There are several reasons why the M_PASSFP message is placed directly on the opposite Stream head:

(1): The message contains a reference to a file pointer (file table entry) within the kernel and must not be freed without also releasing this reference.
(2): The message must not be altered by modules in the Stream.
(3): Although the message contents are structured, the contents rely on implementation specifics of the Stream head. Therefore, the message is of no use to a portable driver or module.

Because the M_PASSFP message is placed directly on the opposite Stream head, although it is message of normal priority, it is treated as a high priority message. M_PASSFP messages can be generated directly by a user level process with the I_SENDFD(7) ioctl(2s). M_PASSFP messages can be consumed directly by a user level process with the I_RECVFD(7) ioctl(2s). M_PASSFP messages should not be generated by drivers or modules. M_PASSFP messages arriving at a driver or module can be discarded (ignored and freed).

USAGE

There is one standard module (besides the Stream head) that needs to generate an pass a M_PASSFP message. That module is connld(4). The connld(4) module must pass a file pointer to the Stream head opposite to the one that is is pushed over, on each open of the Stream. The The OpenSS7 Project[1] implementation of the M_PASSFP message is detailed below, under IMPLEMENTATION ® as documentation for this module and any other module that needs to perform a similar task.

IMPLEMENTATION

Under The OpenSS7 Project[1], the M_PASSFP message contains (indirectly) a file pointer (that is, a pointer to a file structure as defined in <linux/fs.h>). The Stream head allocates the message block using the esballoc(9) utility instead of allocb(9). The free routine and argument to the free routine are special. The free routine argument is the file pointer, and the free routine simply releases the reference to the file pointer. Rather than pointing into the data buffer, b_rptr points to the free routing argument contained in the data block, datab(9), structure, and b_wptr points one byte past the argument.

In this way, M_PASSFP messages sitting on a Stream head read queue can be flushed as normal, using the flushq(9) utility, and the reference to each file pointer will be released.

COMPATIBILITY

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

---: Contents of the M_PASSFP message and implementation of the sth(4) and connld(4) modules are, by nature, implementation specific. Neither can be implemented in a fully portable manner.
: Portable STREAMS drivers and modules will not expect the M_PASSFP message to appear on their queues, and will never generate an M_PASSFP message.
---: M_PASSFP has a different constant value on older versions of OSF/1®[2], and older versions of LiS[3].
: Portable STREAMS drivers and modules will use The OpenSS7 Project[1] instead of LiS[3].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[4].

HISTORY

The M_PASSFP message first appeared in SVR 3[5].

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]: 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/>
[3]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 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

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Thu, 23 May 2013 14:31:47 GMT.

This document was created by man2html, using the manual pages.
Time: 14:31:47 GMT, May 23, 2013