Return to libtsap.3n CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / tsap

Annotation of 43BSDReno/contrib/isode-beta/tsap/libtsap.3n, revision 1.1

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.