![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libtsap.3n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / tsap|
Return to libtsap.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / tsap |
1.1 root 1: .TH LIBTSAP 3N "31 May 1988"
2: .\" $Header: /f/osi/tsap/RCS/libtsap.3n,v 7.0 89/11/23 22:30:28 mrose Rel $
3: .\"
4: .\"
5: .\" $Log: libtsap.3n,v $
6: .\" Revision 7.0 89/11/23 22:30:28 mrose
7: .\" Release 6.0
8: .\"
9: .SH NAME
10: libtsap \- Transport Services library
11: .SH SYNOPSIS
12: .B "#include <isode/tsap.h>"
13: .sp
14: \fIcc\fR\0...\0\fB\-ltsap\fR
15: .SH DESCRIPTION
16: The \fIlibtsap\fR library contains a set of routines which implement
17: transport services on top of the TCP.
18: In essence,
19: they implement a Transport Service Access Point (TSAP) interface to the
20: native TCP/IP implementation on Berkeley UNIX.
21: .PP
22: Although the ISO model is symmetric,
23: the TCP/IP model (and this implementation) is based on a client/server
24: paradigm and hence asymmetric.
25: The information herein is skeletal:
26: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
27: clients are coded and interact with the \fIlibtsap\fR library.
28: .SH ADDRESSES
29: TSAP addresses are represented by the \fBTSAPaddr\fR structure.
30: This contains one more more network addresses,
31: and a transport-selector as found in the \fIisoservices\fR\0(5)
32: database.
33: .SH "SERVER INITIALIZATION"
34: A program providing an ISO service is invoked under \fItsapd\fR\0(8c),
35: with the argument vector listed in the ISODE services database.
36: The server's very first action is to re\-capture the TSAP
37: state as recorded by \fItsapd\fR.
38: This is accomplished by calling \fBTInit\fR.
39: Information returned by this call is equivalent to the parameters passed by a
40: T\-CONNECTION.INDICATION event.
41: If the call is successful,
42: the program can then examine the argument vector that was passed via
43: \fIexecvp\fR
44: (it's important to call \fBTInit\fR prior to reading \fBargc\fR and
45: \fBargv\fR).
46: If the call to \fBTInit\fR is not successful,
47: information returned by the call indicates the reason for failure.
48: .PP
49: After examining the information provided by \fBTInit\fR
50: (and possibly the argument vector),
51: the server should either accept or reject the connection.
52: If accepting, the \fBTConnResponse\fR routine is called
53: (which corresponds to the T\-CONNECT.RESPONSE action).
54: If the call is successful,
55: the interaction is henceforth symmetric.
56: If un\-successful,
57: information returned by the call indicates the reason for failure.
58: If rejecting, the \fBTDiscRequest\fR routine is called
59: (which corresponds to the T\-DISCONNECT.REQUEST action),
60: and the program may exit.
61: .SH "CLIENT INITIALIZATION"
62: A program requesting an ISO service calls \fBTConnRequest\fR
63: (which corresponds to the T\-CONNECT.REQUEST action).
64: If successful,
65: the interaction is henceforth symmetric.
66: If un\-successful,
67: information returned by the call indicates the reason for failure.
68: .SH TRANSPORT\-DESCRIPTORS
69: Once a connection has been established via a successful return from
70: \fBTConnResponse\fR (for servers) or \fBTConnRequest\fR (for clients),
71: a connection is referenced by a small integer
72: (returned in a structure passed to these calls) called a
73: \fItransport\-descriptor\fR.
74: The transport\-descriptor appears as an argument to the peer routines described
75: below.
76: .PP
77: By default,
78: events associated with a transport\-descriptor are synchronous in nature:
79: activity in the network won't generate an INDICATION event without program
80: first asking to be told of any activity.
81: To mark a transport\-descriptor as asynchronous,
82: a call to \fBTSetIndications\fR is made with the addresses of an integer
83: function to handle these events:
84: .sp
85: .in +.5i
86: .nf
87: .ta \w'\fIroutine\fR 'u
88: \fIroutine\fR \fIevents\fR
89: \fBfunc1\fR T\-DATA.INDICATION, T\-EXPEDITED DATA.INDICATION
90: \fBfunc2\fR T\-DISCONNECT.INDICATION
91: .re
92: .fi
93: .in -.5i
94: .sp
95: Upon a successful return from \fBTSetIndications\fR,
96: these functions will be called as appropriate in this fashion:
97: .sp
98: .in +.5i
99: .B "(*func1) (sd, tx);"
100: .sp
101: .B "(*func2) (sd, td);"
102: .in -.5i
103: .sp
104: where \fBsd\fR is the transport\-descriptor,
105: \fBtx\fR is a pointer to a \fBTSAPdata\fR structure,
106: and \fBtd\fR is a pointer to a \fBTSAPdisconnect\fR structure.
107: Any value returned by these functions is ignored.
108: .PP
109: Note well: the \fB\-ltsap\fR library uses the SIGEMT signal to provide this
110: interface.
111: Programs loaded with \fB\-ltsap\fR that use asynchronous transport\-descriptors
112: should NOT use SIGEMT for other purposes.
113: .PP
114: For synchronous multiplexing of several connections,
115: the routine \fBTSelectMask\fR updates a file\-descriptor mask and counter for
116: use with \fIselect\fR\0(2).
117: .SH PEER
118: As a rule,
119: a fatal failure (consult the \fIUser's Manual\fR)
120: on return from any of these routines is equivalent to a
121: T\-DISCONNECT.INDICATION.
122: .sp
123: .in +.5i
124: .nf
125: .ta \w'\fBTWriteRequest\fR 'u
126: \fIroutine\fR \fIaction\fR
127: \fBTDataRequest\fR T\-DATA.REQUEST
128: \fBTExpdRequest\fR T\-EXPEDITED\-DATA.REQUEST
129: \fBTWriteRequest\fR T\-WRITE.REQUEST (write user data vectors)
130: \fBTReadRequest\fR T\-READ.REQUEST (synchronous read)
131: \fBTDiscRequest\fR T\-DISCONNECT.REQUEST
132: .re
133: .fi
134: .in -.5i
135: .sp
136: Note that the \fBTReadRequest\fR routine returns data from the peer by
137: allocating memory.
138: It should be freed before the structure is re\-used.
139: .PP
140: Finally,
141: the routine \fBTErrString\fR takes a failure code from a \fBTSAPdisconnect\fR
142: structure and returns a null\-terminated diagnostic string.
143: Also,
144: the routine \fBTLocalHostName\fR returns a null\-terminated string
145: denoting the name of the localhost.
146: .SH FILES
147: .nf
148: .ta \w'\*(EDisoservices 'u
149: \*(EDisoservices ISODE services database
150: .re
151: .fi
152: .SH "SEE ALSO"
153: isoc(1c), isoservices(5), isod(8c), isore(8c), tsapd(8c),
154: .br
155: \fIThe ISO Development Environment: User's Manual\fR,
156: .br
157: \fIRFC1006: ISO Transport Services on top of the TCP, Version: 3\fR,
158: .br
159: ISO 8072:
160: \fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
161: Transport Service Definition\fR,
162: .br
163: CCITT Recommendation X.214:
164: \fITransport Service Definition for Open Systems Interconnection (OSI) for
165: CCITT Applications\fR
166: .SH DIAGNOSTICS
167: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
168: In addition,
169: those routines which take a pointer to a \fBTSAPdisconnect\fR structure
170: fill\-in the structure as appropriate.
171: .SH AUTHORS
172: Marshall T. Rose
173: .br
174: Dwight E. Cass,
175: Northrop Research and Technology Center
176: .SH BUGS
177: Do not confuse transport\-descriptors with file\-descriptors.
178: Unlike file\-descriptors which are implemented by the kernel,
179: transport\-descriptors do not work across \fIfork\fRs and \fIexec\fRs.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.