usr/src/man/man7m/tirdwr.7m

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH TIRDWR 7M "Jul 3, 1990"
   8 .SH NAME
   9 tirdwr \- Transport Interface read/write interface STREAMS module
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBint ioctl( \fR\fIfd, \fR\fBI_PUSH\fR\fI, \fR\fB"tirdwr");\fR
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 \fBtirdwr\fR is a STREAMS module  that provides an alternate interface to a
  20 transport provider which supports the  Transport Interface ("\fBTI\fR")
  21 functions of the Network Services library (see Section 3N). This alternate
  22 interface allows a user to communicate with the transport protocol  provider
  23 using the  \fBread\fR(2) and  \fBwrite\fR(2) system calls. The  \fBputmsg\fR(2)
  24 and  \fBgetmsg\fR(2) system calls may also be used. However, \fBputmsg\fR and
  25 \fBgetmsg\fR can only transfer data messages between  user and stream; control
  26 portions are disallowed.
  27 .sp
  28 .LP
  29 The \fBtirdwr\fR module must only be pushed (see \fBI_PUSH\fR in
  30 \fBstreamio\fR(7I)) onto a stream terminated by a transport protocol provider
  31 which supports the \fBTI\fR. After the \fBtirdwr\fR module has been pushed onto
  32 a stream, none of the \fBTI\fR functions can be used. Subsequent calls to
  33 \fBTI\fR functions cause an error on the stream. Once the error is detected,
  34 subsequent system calls on the stream return an error with \fBerrno\fR set to
  35 \fBEPROTO\fR.
  36 .sp
  37 .LP
  38 The following are the actions taken by the \fBtirdwr\fR module when pushed on
  39 the stream, popped (see \fBI_POP\fR in  \fBstreamio\fR(7I)) off  the stream, or
  40 when data passes through it.
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBpush\fR\fR
  45 .ad
  46 .RS 9n
  47 When the module is pushed onto a stream, it checks any existing data destined
  48 for the user to ensure that only regular data messages are present. It ignores
  49 any messages on the stream that relate to process management, such as messages
  50 that generate signals to the user processes associated with the stream. If any
  51 other messages are present, the \fBI_PUSH\fR will return an error with
  52 \fBerrno\fR set to \fBEPROTO\fR.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBwrite\fR\fR
  59 .ad
  60 .RS 9n
  61 The module takes the following actions on data that originated from a
  62 \fBwrite\fR system call:
  63 .RS +4
  64 .TP
  65 .ie t \(bu
  66 .el o
  67 All messages with the exception of messages that contain control portions (see
  68 the \fBputmsg\fR and \fBgetmsg\fR system calls) are transparently passed onto
  69 the module's downstream neighbor.
  70 .RE
  71 .RS +4
  72 .TP
  73 .ie t \(bu
  74 .el o
  75 Any zero length data messages are freed by the module and they will not be
  76 passed onto the module's downstream neighbor.
  77 .RE
  78 .RS +4
  79 .TP
  80 .ie t \(bu
  81 .el o
  82 Any messages with control portions generate an error, and any further system
  83 calls associated with the stream fails with \fBerrno\fR set to \fBEPROTO\fR.
  84 .RE
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBread\fR\fR
  91 .ad
  92 .RS 9n
  93 The module takes the following actions on data that originated from the
  94 transport protocol provider.
  95 .sp
  96 All messages with the exception of those that contain control portions (see the
  97 \fBputmsg\fR and \fBgetmsg\fR system calls) are transparently passed onto the
  98 module's upstream neighbor. The action taken on messages with control portions
  99 will be as follows:
 100 .RS +4
 101 .TP
 102 .ie t \(bu
 103 .el o
 104 Any data messages with control portions have the control portions removed from
 105 the message before to passing the message on to the upstream neighbor.
 106 .RE
 107 .RS +4
 108 .TP
 109 .ie t \(bu
 110 .el o
 111 Messages that represent an orderly release indication from the transport
 112 provider generate a zero length data message, indicating the end of file, which
 113 will be sent to the reader of the stream. The orderly release message itself is
 114 freed by the module.
 115 .RE
 116 .RS +4
 117 .TP
 118 .ie t \(bu
 119 .el o
 120 Messages that represent an abortive disconnect indication from the transport
 121 provider cause all further \fBwrite\fR and \fBputmsg\fR system calls to fail
 122 with \fBerrno\fR set to \fBENXIO\fR. All further \fBread\fR and \fBgetmsg\fR
 123 system calls return zero length data (indicating end of file) once all previous
 124 data has been read.
 125 .RE
 126 .RS +4
 127 .TP
 128 .ie t \(bu
 129 .el o
 130 With the exception of the above rules, all other messages with control portions
 131 generate an error and all further system calls associated with the stream will
 132 fail with \fBerrno\fR set to \fBEPROTO\fR.
 133 .RE
 134 Any zero length data messages are freed by the module and they are not passed
 135 onto the module's upstream neighbor.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBpop\fR\fR
 142 .ad
 143 .RS 9n
 144 When the module is popped off the stream or the stream is closed, the module
 145 takes the following action:
 146 .RS +4
 147 .TP
 148 .ie t \(bu
 149 .el o
 150 If an orderly release indication has been previously received, then an orderly
 151 release request will be sent to the remote side of the transport connection.
 152 .RE
 153 .RE
 154
 155 .SH SEE ALSO
 156 .sp
 157 .LP
 158 \fBIntro\fR(3), \fBgetmsg\fR(2), \fBputmsg\fR(2), \fBread\fR(2),
 159 \fBwrite\fR(2), \fBIntro\fR(3), \fBstreamio\fR(7I), \fBtimod\fR(7M)
 160 .sp
 161 .LP
 162 \fISTREAMS Programming Guide\fR