OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 12:53:40 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of SPX
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Manpage of SPX

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


SPX

Section: The OpenSS7 Project Devices (4)
Updated: Wed, 30 Jul 2014 07:01:18 GMT
Index Return to Main Contents

NAME

spx, pipe - STREAMS bi-directional pipe device

DESCRIPTION

The software pipes obtained by the system call pipe(2s) are not necessarily bidirectional[1..3]. The spx STREAMS pseudo-device driver provide a mechanism for obtaining STREAMS-based pipes that are bidirectional in nature.

The spx pseudo-device driver is a regular STREAMS device driver.

Because the open(2s) system call only returns one file descriptor, the following procedure is used to create two file descriptors with a connected STREAMS-based pipe between them:

(1)
Open /dev/spx an obtain a first file descriptor. At this point there is only half of the pipe available. This step obtains fd[0].
(2)
Open /dev/spx again to obtain a second file descriptor. At this point there are two unconnected stream heads. This step obtains fd[2].
(2)
Call ioctl(2s) with the I_FDINSERT command (see streamio(7)) to associate fd[0] with fd[1]. This can either be accomplished by performing an I_FDINSERT with fd[1] on the stream returned as fd[0]; or, with fd[0] on fd[1]. The data part of the I_FDINSERT command is ignored, and the control part of the I_FDINSERT command contains only the file descriptor translated to a queue pointer. This step connects fd[0] to fd[1] for a fully connected, STREAMS-based, bi-directional pipe.

Characteristics

Following are some characteristics of STREAMS-based pips that cause their behaviour to differ from that of regular STREAMS character special device files:

*
STREAMS-based pipes cannot be clone opened. But see connld(4).
*
STREAMS-based pipes have both ends open for both read and write.
*
When a STREAMS-based pipe is hung up, or the other end of the STREAMS-based pipe is closed, write and write-like operations return [EPIPE] and generate a {SIGPIPE} signal to the caller, instead of simply returning [ENXIO] as is the case for regular STREAMS devices. This is true for write(2s), writev(2s), putmsg(2), putpmsg(2s), and streamio(7) input-output controls that write messages to the Stream, such as I_FDINSERT(7).
*
By default, when an asynchronous write error occurs, and a write or write-like operation is performed, STREAMS-based pipes will generate {SIGPIPE} to the caller in addition to returning the error from the asynchronous write error message. This behavior can be suppressed by clearing the SNDPIPE option using the I_SWROPT(7) input-output control. This is the reverse of the default behavior for regular STREAMS character special files.
*
By default, attempting to write a zero-length data message to a STREAMS-based pipe with write(2s), writev(2s), putmsg(2), or putpmsg(2s), will succeed, return zero, but no message will be generated. Generation of the message can be enabled by setting the SNDZERO option using the I_SWROPT(7) input-output control. This is the reverse of the default behaviour for regular STREAMS character special files.
*
STREAMS-based pipes break large writes down into independent data messages of 4096 bytes or less. Writes of less than or equal to 4096 bytes are guaranteed atomic. Writes of greater than 4096 byes are not guaranteed atomic. This is default behaviour of all STREAMS character special files, unless altered by the driver.
*
An end of a STREAMS-based pipes that has no modules pushed, even when full and blocked on write, will not block on close as described under I_SETCLTIME(7), because there is no driver write queue.
*
I_LIST(7) will not report a count for a driver on either end of a STREAMS-based pipe (STREAMS-based pipes have no driver).
*
I_LINK(7), I_PLINK(7), I_UNLINK(7), and I_PUNLINK(7), will always fail with error [EINVAL] on a STREAMS-based pipe.
*
I_SENDFD(7) and I_RECVFD(7) will operate on a STREAMS-based pipe (whereas they fail on a regular STREAMS character special file).

USAGE

The characteristics of bi-directional STREAMS-based pipes, by comparison to SVR 3[4] style pipes is as follows:

*
STREAMS-based pipes are bi-directional. Both sides are opened for both read and write. Data written to one end of the pipe can be read by the other. Both ends of the pipe can have data written and read.
*
STREAMS-based pipes can have modules pushed and popped from either side of the pipe. However, before pushing a STREAMS module on either side of the STREAMS-based pipe, the pipemod(4) module should be pushed on one end of the STREAMS-based pipe to reverse the sense of M_FLUSH(9) bits for proper flushing of the pipe.
*
STREAMS-based pipes can have the connld(4) module can be pushed onto one end of the pipe.
*
STREAMS-based pipes have controllable flow control and minimum and maximum packet size characteristics.
*
STREAMS-based pipes permit the use of the getmsg(2), getpmsg(2s), putmsg(2) and putpmsg(2s) system calls on the pipe ends.
*
STREAMS-based pipes permit the use of STREAMS IO controls on either pipe end. See streamio(7).

NOTICES

Although an stat(2) on the /dev/spx device node will show the node as being a character special device with a device number corresponding to the spx driver, an fstat(2) on the file descriptor resulting from an open(2s) call on /dev/spx will indicate that the file is a fifo. This is rather normal UNIX® behaviour.

Depending on Linux® kernel configuration parameters, it might not be necessary to go to this extent to create a STREAMS-based bidirectional pipe. When kernel configuration parameter CONFIG_STREAMS_PIPES_REPLACE is set, then the SVR 3[4] pipe approach used by Linux® will be replaced with a bi-directional STREAMS-based pipe. Then, a simple call to pipe(2s) will return a bidirectional pipe and it is not necessary to open the spx driver to obtain one.

When first opened, a spx device behaves similar to an Echo Device, echo(4).

Under The OpenSS7 Project it is possible to make all Linux system pipes STREAMS-based. This must be done when the package is configured and will be effected when the STREAMS pipe kernel module is loaded. Once the kernel module is loaded all pipes subsequently opened with the pipe(2s) system call will be STREAMS-based.

IMPLEMENTATION

spx is not implemented as a normal STREAMS driver: it is implemented as a shadow special device node under Linux Fast-STREAMS[5]. Linux Fast-STREAMS shadow special devices nodes call pipe_open() from cdev_open() instead of spec_open() permitting the pipe device to intercept and redirect the open call to the appropriate device. This is consistent with the descriptions for the internal pipe_open() under SVR 4[6].

EXAMPLES

Following is an example of how to open a STREAMS-based pipe:

int
spipe(int *fd)
{
    int fds[2];
    long ptr;
    struct strfdinsert fdi;
    if ((fds[0] = open("/dev/spx", O_RDWR)) < 0)
        return (-1);
    if ((fds[1] = open("/dev/spx", O_RDWR)) < 0) {
        close(fds[0]);
        return (-1);
    }
    fdi.ctlbuf.maxlen = fdi.ctlbuf.len = sizeof(ptr);
    fdi.ctlbuf.buf = (caddr_t) &ptr;
    fdi.databuf.maxlen = fdi.databuf.len = -1;
    fdi.databuf.buf = NULL;
    fdi.filedes = fds[0];
    fdi.offset = 0;
    fdi.flags = RS_NORM;
    if (ioctl(fds[0], I_FDINSERT, &fdi) < 0) {
        close(fds[0]);
        close(fds[1]);
        return (-1);
    }
    fd[0] = fds[0];
    fd[1] = fds[1];
    return (0);
}

DEVICES

/dev/spx
The external filesystem STREAMS pipe device.
/dev/streams/spx, /devices/spx
The specfs(5) shadow special filesystem STREAMS pipe deivce.

SEE ALSO

pipe(2s), open(2s), ioctl(2s), streamio(7), pipemod(4), connld(4), echo(4), getmsg(2), getpmsg(2s), putmsg(2), putpmsg(2s), stat(2), fstat(2).

BUGS

spx has no known bugs.

COMPATIBILITY

Linux Fast-STREAMS[5] provides the spx device for compatibility with UnixWare® 7 and AIX®. Solaris® and LiS[7] do not provide an spx driver.

---
AIX® provides a spx driver. The use of the spx driver under AIX® is not well documented.
---
UnixWare® provides a spx driver. The use of the spx driver under UnixWare® is not well documented.
---
LiS
---
UnixWare® documentation[8] describes naming an unnamed pipe by making a device node with the device number returned by a call to stat(2) on one end of the pipe. Although this technique also works with Linux Fast-STREAMS, we recommend using fattach(2) instead.

CONFORMANCE

AIX® and UnixWare® 7.1.1 documentation. Conformance is verified using the test-pipe(8) verification test suite.

HISTORY

spx appears in AIX® and UnixWare® 7.1.1.

REFERENCES

[1]
XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[2]
SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]
SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[4]
SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[5]
streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[6]
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]
[7]
LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[8]
UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.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

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Wed, 30 Jul 2014 07:01:18 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

NAME
DESCRIPTION
Characteristics
USAGE
NOTICES
IMPLEMENTATION
EXAMPLES
DEVICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 07:01:18 GMT, July 30, 2014
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of SPX
Last modified: Mon, 28 Apr 2008 12:53:40 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.