tirdwr.4

7号信令功能代码,为开源代码

'\" rtp
.\" -*- nroff -*-
.\"
.\" @(#) tirdwr.4,v 1.1.4.1 2004/01/12 23:45:06 brian Exp
.\"
.\" =========================================================================
.\"
.\" Copyright (C) 2001-2004  OpenSS7 Corporation <www.openss7.com>
.\"
.\" All Rights Reserved.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" -------------------------------------------------------------------------
.\"
.\" U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software
.\" on behalf of the U.S. Government ("Government"), the following
.\" provisions apply to you.  If the Software is supplied by the Department
.\" of Defense ("DoD"), it is classified as "Commercial Computer Software"
.\" under paragraph 252.227-7014 of the DoD Supplement to the Federal
.\" Acquisition Regulations ("DFARS") (or any successor regulations) and the
.\" Government is acquiring only the license rights granted herein (the
.\" license rights customarily provided to non-Government users).  If the
.\" Software is supplied to any unit or agency of the Government other than
.\" DoD, it is classified as "Restricted Computer Software" and the
.\" Government's rights in the Software are defined in paragraph 52.227-19
.\" of the Federal Acquisition Regulations ("FAR") (or any success
.\" regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
.\" NASA Supplement to the FAR (or any successor regulations).
.\"
.\" =========================================================================
.\"
.\" Modified 2004/01/12 23:45:06 by brian
.\"
.\" =========================================================================
.so lis.macros
.R1
bracket-label "\fR[\fB" "\fR]" "\fR, \fB"
no-default-database
database lis.refs
accumulate
move-punctuation
abbreviate A
join-authors ", " ", " " and "
et-al " et al" 2 3
abbreviate-label-ranges ".."
sort-adjacent-labels
.R2
.\"
.\"
.TH TIRDWR 4 "2004/01/12 23:45:06" "LiS-2_16_18-8" "Linux STREAMS"
.\"
.\"
.SH NAME
.B tirdwr
\- a STREAMS XTI/TLI read write compaibility module
.\"
.\"
.SH SYNOPSIS
.PP
.B #include <sys/stropt.h>
.br
.B #include <xti.h>
.HP 8
.BI "" tli_stream " = t_open(" tli_device ", " 0 );
.PD 0
.HP 8
.BI t_connect( tli_stream ", " sndcall );
.PD
.HP 8
.BI read( tli_stream ", " ... );
.HP 8
.BI write( tli_stream ", " ... );
.HP 8
.BI ioctl( tli_stream ", " \fRI_PUSH\fP ", " \*(lqtirdwr\*(rq );
.PD 0
.HP 8
.BI ioctl( tli_stream ", " \fRI_POP\fP ", " \*(lqtirdwr\*(rq );
.HP 8
.BI close( tli_stream );
.PD
.\"
.\"
.SH DESCRIPTION
.PP
The
.B tirdwr
module is a STREAMS module that provides a transport user supporting the
.I \(lqTransport Provider Interface\(rq
(TPI)
.[
TPI Revision 5
.]
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
.BR read (2),
.BR readv (2),
.BR write (2)
and
.BR writev (2)
system calls.  It can also continue to use the
.BR putmsg (2),
.BR putpmsg (2),
.BR getmsg (2)
and
.BR getpmsg (2)
system calls, but these functions will only transfer data messages between the
user process and device stream.
.PP
The user places the
.B tirdwr
module on a device stream by calling the STREAMS
.BR I_PUSH
ioctl
.RB (see " streamio" (7)).
Once the module has been pushed, the user cannot make further
.BR xti (3)
library calls.  Attempts to do so will result in failure with
.IR errno (3)
set to
.RB [ EPROTO ].
The user removes the
.B tirdwr
module from a device by calling the STREAMS
.B I_POP
ioctl
.RB (see " streamio" (7)),
or by closing the stream with
.BR t_close (3)
or
.BR close (2).
.PP
The behavior of the
.B tirdwr
module when pushed or popped, or subjected to
.BR xti (3)
library calls and system calls is described below:
.\"
.\"
.SS "I_PUSH
.PP
The actions taken when the
.B tirdwr
module are as follows:
.IP \(bu \w'\(bu\ \ 'u
When the
.B tirdwr
module is pushed on the stream, and as part of the
.BR 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
.B tirdwr
returns error
.RB [ EPROTO ]
to the module open routine and fails the push on the stream.
.IP \(bu
If no such messages exist, the module is successfully pushed onto the stream.
.\"
.\"
.SS "Write
.PP
The actions taken when data is written to the stream with
.BR write "(2), " writev "(2), " putmsg "(2) or " putpmsg (2)
are as follows:
.IP \(bu \w'\(bu\ \ 'u
All non-zero length
.B M_DATA
messages with no control portions are passed downstream.
Zero-length
.B N_DATA
messages are freed and not passed downstream.
.IP \(bu
A messages with control portions result in a
.B M_ERROR
message being passed upstream with read and write error
.RB [ EPROTO ].
This results in all further system calls on the stream failing with an
.IR errno (3)
of
.RB [ EPROTO ].
.\"
.\"
.SS "Read
.PP
The actions taken when data arrives at the lower interface to the
.B tirdwr
module are as follows:
.IP \(bu \w'\(bu\ \ 'u
.B M_DATA
messages will be passed through transparently.
.IP \(bu
.BR T_EXDATA_IND (7)
(or
.BR T_OPTDATA_IND (7)
indicating expedited data)
will cause an
.B M_ERROR
message to be issued with a read and write side error of
.RB [ EPROTO ].
This will cause all further system calls on the stream to fail with
.IR errno (3)
set to
.RB [ EPROTO ].
.IP \(bu
.BR T_DATA_IND (7)
(or
.BR T_OPTDATA_IND (7)
indicating normal data)
will have the control portions stripped and only the
.B M_DATA
blocks in the message will be passed upstream.
Zero length data portions will not be passed upstream, but will be freed.
.IP \(bu
.BR T_ORDREL_IND (7)
received will cause the stream to be marked as having received a
.BR T_ORDREL_IND (7),
and a zero-length
.B M_DATA
message will be passed upstream causing the last
.BR read (2)
operation to return zero (0) indicating end of file.
.IP \(bu
.BR T_DISCON_IND (7)
received will cause an
.B M_HANGUP
message to be issued to the stream head.
This will cause all further write system calls
.RB ( write "(2), " writev "(2), " putmsg "(2) and " putpmsg (2))
to fail with
.IR errno (3)
set to
.RB [ ENXIO ].
All further read system calls
.RB ( read "(2), " readv "(2), " getmsg "(2) and " getpmsg (2))
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.
.IP \(bu
All other messages with control portions result in a
.B M_ERROR
message being sent upstream with a
.RB [ EPROTO ]
read and write error code.  This will cause all subsequent system calls on the
stream to fail with
.IR errno (3)
set to
.RB [ EPROTO ].
This does not occur in normal usage.
.\"
.\"
.SS "XTI/TLI Library Calls
.PP
The actions taken in response to XTI/TLI Library Calls are as follows:
.IP \(bu \w'\(bu\ \ 'u
All XTI library calls that perform an operation generating an
.BR M_PROTO ,
.B M_PCPROTO
or
.B M_IOCTL
on the stream will result in failure of that and all subsequent
.BR xti (3)
library and system calls with error
.RB [ EPROTO ].
.\"
.\"
.SS "I_POP
.PP
The actions taken when the
.B tirdwr
module is popped are as follows:
.IP \(bu \w'\(bu\ \ 'u
If a
.BR T_ORDREL_IND (7)
has been previously received by the
.B tirdwr
module for the stream, no
.BR T_DISCON_IND (7)
has been received for the stream
and the stream has not otherwise encountered an error, a
.BR T_ORDREL_REQ (7)
is issued downstream before closing the
.B tirdwr
module.
.IP \(bu
If no
.BR T_ORDREL_IND (7)
or
.BR T_DISCON_IND (7)
has been received for the stream, a
.BR T_DISCON_REQ (7)
is issued downstream before closing the
.B tirdwr
module.
.IP \(bu
If an error has been encountered on the stream and no
.BR T_DISCON_IND (7)
has been received for the stream, a
.BR T_DISCON_REQ (7)
is issued downstream before closing the
.B tirdwr
module.
.\"
.\"
.SH USAGE
.PP
.B tirdwr
is only suitable for connection-oriented transport service providers of type
.I T_COTS
or
.IR T_COTS_ORD .
.PP
The
.B tirdwr
module is typically pushed on an XTI/TLI stream after it has been opened,
bound and placed in the connected state using
.BR xti (3)
library calls.
Once the stream is in the connected state, the
.B tirdwr
module is pushed and further access to the stream is formed using only the
.BR read "(2), " readv "(2), " write "(2) and " writev (2)
system calls.
.\"
.\"
.SH RETURN VALUE
.PP
Upon success, a
.BR read (2),
.BR readv (2),
.BR write "(2) or "
.BR 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.
.\"
.\"
.SH ERRORS
.PP