OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 18:38:32 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
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

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


TIRDWR

Section: The OpenSS7 Project Devices (4)
Updated: Sun, 25 Jun 2017 11:34:46 GMT
Index Return to Main Contents

NAME

tirdwr - a STREAMS XTI/TLI read write compaibility module

SYNOPSIS

#include <sys/stropt.h>
#include <xti.h>

tli_stream = t_open(tli_device, 0);
t_connect(tli_stream, sndcall);
read(tli_stream, ...);
write(tli_stream, ...);
ioctl(tli_stream, I_PUSH, ``tirdwr'');
ioctl(tli_stream, I_POP, ``tirdwr'');
close(tli_stream);

DESCRIPTION


The tirdwr module is a STREAMS module that provides a transport user supporting the Transport Provider Interface (TPI)[1] with an alternate interface to a transport protocol provider supporting TPI. This alternate interface allows the transport user to communicate with the transport protocol provider using the read(2), readv(2), write(2) and writev(2) system calls. It can also continue to use the putmsg(2), putpmsg(2s), getmsg(2) and getpmsg(2s) system calls, but these functions will only transfer data messages between the user process and device stream.

The user places the tirdwr module on a device stream by calling the STREAMS I_PUSH ioctl (see streamio(7)). Once the module has been pushed, the user cannot make further xti(3) library calls. Attempts to do so will result in failure with errno(3) set to [EPROTO]. The user removes the tirdwr module from a device by calling the STREAMS I_POP ioctl (see streamio(7)), or by closing the stream with t_close(3) or close(2).

The behavior of the tirdwr module when pushed or popped, or subjected to xti(3) library calls and system calls is described below:

I_PUSH

The actions taken when the tirdwr module are as follows:

*
When the tirdwr module is pushed on the stream, and as part of the qopen(9) procedure for the module, the module check if there are any messages with control parts that it would not have normally passed that are queued for read at the stream head. If such messages exist, the tirdwr returns error [EPROTO] to the module open routine and fails the push on the stream.
*
If no such messages exist, the module is successfully pushed onto the stream.

Write

The actions taken when data is written to the stream with write(2), writev(2), putmsg(2) or putpmsg(2s) are as follows:

*
All non-zero length M_DATA messages with no control portions are passed downstream. Zero-length N_DATA messages are freed and not passed downstream.
*
A messages with control portions result in a M_ERROR message being passed upstream with read and write error [EPROTO]. This results in all further system calls on the stream failing with an errno(3) of [EPROTO].

Read

The actions taken when data arrives at the lower interface to the tirdwr module are as follows:

*
M_DATA messages will be passed through transparently.
*
T_EXDATA_IND(7) (or T_OPTDATA_IND(7) indicating expedited data) will cause an M_ERROR message to be issued with a read and write side error of [EPROTO]. This will cause all further system calls on the stream to fail with errno(3) set to [EPROTO].
*
T_DATA_IND(7) (or T_OPTDATA_IND(7) indicating normal data) will have the control portions stripped and only the M_DATA blocks in the message will be passed upstream. Zero length data portions will not be passed upstream, but will be freed.
*
T_ORDREL_IND(7) received will cause the stream to be marked as having received a T_ORDREL_IND(7), and a zero-length M_DATA message will be passed upstream causing the last read(2) operation to return zero (0) indicating end of file.
*
T_DISCON_IND(7) received will cause an M_HANGUP message to be issued to the stream head. This will cause all further write system calls (write(2), writev(2), putmsg(2) and putpmsg(2s)) to fail with errno(3) set to [ENXIO]. All further read system calls (read(2), readv(2), getmsg(2) and getpmsg(2s)) will continue to read data until all pending data is read. Read system calls will return zero (0) indicating end of file once all pending data has been read.
*
All other messages with control portions result in a M_ERROR message being sent upstream with a [EPROTO] read and write error code. This will cause all subsequent system calls on the stream to fail with errno(3) set to [EPROTO]. This does not occur in normal usage.

XTI/TLI Library Calls

The actions taken in response to XTI/TLI Library Calls are as follows:

*
All XTI/TLI library calls that perform an operation generating an M_PROTO, M_PCPROTO or M_IOCTL on the stream will result in failure of that and all subsequent xti(3) library and system calls with error [EPROTO].

I_POP

The actions taken when the tirdwr module is popped are as follows:

*
If a T_ORDREL_IND(7) has been previously received by the tirdwr module for the stream, no T_DISCON_IND(7) has been received for the stream and the stream has not otherwise encountered an error, a T_ORDREL_REQ(7) is issued downstream before closing the tirdwr module.
*
If no T_ORDREL_IND(7) or T_DISCON_IND(7) has been received for the stream, a T_DISCON_REQ(7) is issued downstream before closing the tirdwr module.
*
If an error has been encountered on the stream and no T_DISCON_IND(7) has been received for the stream, a T_DISCON_REQ(7) is issued downstream before closing the tirdwr module.

USAGE

tirdwr is only suitable for connection-oriented transport service providers of type T_COTS or T_COTS_ORD.

The tirdwr module is typically pushed on an XTI/TLI stream after it has been opened, bound and placed in the connected state using xti(3) library calls. Once the stream is in the connected state, the tirdwr module is pushed and further access to the stream is formed using only the read(2), readv(2), write(2) and writev(2) system calls.

RETURN VALUE

Upon success, a read(2), readv(2), write(2) or writev(2) system call will return zero or the number of bytes read or written. If the number of bytes read is zero it indicates end of file. Upon failure, these calls will return -1.

ERRORS

When a read(2), readv(2), write(2) or writev(2) system call fails, it returns -1 and sets errno(3) to an appropriate error number as documented on the appropriate manual page. In addition, tirdwr may return the following errors in response to a read(2), readv(2), write(2) or writev(2):

[EPROTO]
The stream user has violoated the read-write protocol. This error will be returned on all subsequent read or write operations. The stream must be closed and re-opened.
[ENXIO]
An attempt was made to write to the stream, however, the transport connection was disconnected in an unorderly fashion. All subsequent write operations on the stream will fail with this error. Read operations will continue to read buffered data. This is similar to the [EPIPE] error of pipe(2s).

NOTICES

Any data associated with abortive disconnect T_DISCON_IND(7) or orderly release T_ORDREL_IND(7) is discarded. It is unclear whether this is correct behavior or not.

Due to interaction with the read(2), readv(2), write(2) and writev(2) system calls, the priority forms of the getmsg(2), getpmsg(2s), putmsg(2) and putpmsg(2s) system calls, and non-zero band form of the getpmsg(2s) and putpmsg(2s) system calls, cannot be used with tirdwr. Use of the putmsg(2) or putpmsg(2s) system calls in this fashion will result in an [EPROTO] error being returned and subsequent failure of all system calls on the stream. Use of the getmsg(2) or getpmsg(2s) system calls cannot be detected by the module and should be avoided by the user.

When system calls putmsg(2) and putpmsg(2s) are used in conjunction with tirdwr, no control part can be specified. Specification of a control part will result in an [EPROTO] error and failure of all subsequent system calls on the stream. When system calls getmsg(2) and getpmsg(2s) are used in conjunction with tirdwr, no control part will be returned.

MODULES

tirdwr STREAMS module.

SEE ALSO

T_ORDREL_IND(7), T_DISCON_IND(7), errno(3), write(2), read(2), T_OPTDATA_IND(7), T_DISCON_REQ(7), xti(3), writev(2), tpi(7), timod(4), t_open(3), t_connect(3), socksys(4), sockmod(4), readv(2), read(2), qopen(9), putpmsg(2s), putmsg(2), getpmsg(2s), getmsg(2), T_ORDREL_REQ(7), T_EXDATA_IND(7), T_DATA_IND(7), test-tirdwr(8).

FILES

/lib/modules/`uname -r`/streams-timod.o

BUGS

tirdwr has been tested with the /usr/bin/test-tirdwr conformance test suite.

tirdwr has no known bugs.

COMPATIBILITY

tirdwr is compatible with XNS 5.2[2] and SVR 4.2[3], and descriptions for UnixWare7®[4], AIX®[5], DigitalUNIX®[6], HP-UX®[7], Solaris®[8], SUPER-UX®[9], with the following portability considerations:

This Linux Fast-STREAMS[10] implementation of tirdwr was backported to LiS[11] to repair serious bugs in the previous LiS implementation. LiS previously had a implementation of tirdwr that was full of bugs. This implementation is free of these many bugs and is, therefore, not compatible with the old buggy tirdwr. Following are the bugs exhibited by the old implementation:

---
Zero length data messages, whether they have a control portion or not, are not supposed to be passed upstream by the tirdwr module. This is because a zero-length data message will generate an end-of-file condition for read(2), readv(2), getmsg(2) and getpmsg(2s). The tirdwr module that comes with LiS[11] passes all M_DATA and T_DATA_IND(7) M_DATA portions upstream without examining them to see if they contain zero-length data messages. This is a bug with no work around. When a T_DISCON_IND(7) primitive is received by the tirdwr module, it is supposed to cause all further write system calls (write(2), writev(2), putmsg(2) and putpmsg(2s)) to fail with error [ENXIO]; however, all read system calls (read(2), readv(2), getmsg(2) and getpmsg(2s)) system calls are supposed to succeed. This corresponds to a hungup stream head that has been sent a M_HANGUP message. The tirdwr module that comes with LiS[11] uses the putctl1(9) form of the M_ERROR message which causes all system calls to fail with error [ENXIO]. This is a bug with no workaround.
---
When the tirdwr module is pushed on a TI stream, all XTI/TLI library calls are supposed to fail and return error [EPROTO], causing all further system calls to fail on the stream. The tirdwr module that comes with LiS[11] passes M_IOCTL, M_IOCDATA, M_IOCACK, M_IOCNAK, M_COPYIN and M_COPYOUT messages transparently, meaning that a number of XTI/TLI functions will not generate an error. This is a bug. A workaround is to refrain from calling XTI/TLI functions on streams upon which tirdwr has been pushed.
---
When a tirdwr module receives an M_READ message from upstream and a T_ORDREL_IND(7) has been received and processed for the stream, a zero-length M_DATA block or a read size M_ERROR message should be sent upstream in response to reassert end-of-file and to keep the reader from blocking indefinitely on read system calls after an orderly release. The tirdwr module that comes with LiS[11] does not perform this function. Coupled with passing zero-length data messages on the read side, this can cause problem with loopback transports and make it difficult to determine when an end-of-file has actually occurred and yet not block indefinitely in synchronous file mode.
---
When the tirdwr module is popped (closed) and no T_ORDREL_IND(7) or T_DISCON_IND(7) has been received for the stream, or if the stream has encountered an error and has not received a T_DISCON_IND(7), the tirdwr module should send a T_DISCON_REQ(7) downstream before completing the close. The tirdwr mdoule that comes with LiS[11] does not send T_DISCON_REQ(7) in any circumstance. The workaround is to always close the stream instead of popping the module using I_POP.

CONFORMANCE

SVID[12], XID[13], XNS 5.2[2], SUSv2[14], SUSv3/POSIX[15],

HISTORY

tirdwr first appeared in SVR 3[16]

REFERENCES

[1]
TLI, Transport Provider Interface Specification, Revision 1.5, Draft 2, December 10, 1992, (Parsippany, New Jersey), UNIXInternational,Inc., Unix International Press. <http://www.openss7.org/doc/tpi.pdf>
[2]
XNS, Open Group CAE Specification: Technical Standard: Network Services (XNS), Issue 5.2, Draft 2, 1999, (Berkshire, UK), OpenGroup, Open Group Publication. [ISBN 1-85912-241-8] <http://www.opengroup.org/onlinepubs/>
[3]
SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]
UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[5]
AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[6]
Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[7]
HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[8]
Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[9]
SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[10]
streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[11]
LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[12]
SVID, System V, Interface Definition, Fourth Edition.
[13]
XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[14]
SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[15]
SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[16]
SVR 3, UNIX® System V Release 3 Programmer's Manual, (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 Sun, 25 Jun 2017 11:34:46 GMT.

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



Index

NAME
SYNOPSIS
DESCRIPTION
I_PUSH
Write
Read
XTI/TLI Library Calls
I_POP
USAGE
RETURN VALUE
ERRORS
NOTICES
MODULES
SEE ALSO
FILES
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 11:34:46 GMT, June 25, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Last modified: Mon, 28 Apr 2008 18:38:32 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.