Return to librtsap.3n CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/rtsap/librtsap.3n, revision 1.1

1.1     ! root        1: .TH LIBRTSAP 3N "23 Sep 1986"
        !             2: .\" $Header: /f/osi/rtsap/RCS/librtsap.3n,v 7.0 89/11/23 22:22:15 mrose Rel $
        !             3: .\"
        !             4: .\"
        !             5: .\" $Log:      librtsap.3n,v $
        !             6: .\" Revision 7.0  89/11/23  22:22:15  mrose
        !             7: .\" Release 6.0
        !             8: .\" 
        !             9: .SH NAME
        !            10: librtsap \- Reliable Transfer Services library
        !            11: .SH SYNOPSIS
        !            12: .B "#include <isode/rtsap.h>"
        !            13: .sp
        !            14: \fIcc\fR\0...\0\fB\-lisode\fR
        !            15: .SH DESCRIPTION
        !            16: The \fIlibrtsap\fR library contains a set of routines which implement
        !            17: reliable transfer facilities.
        !            18: In essence,
        !            19: they implement a Reliable Transfer Service Point (RtSAP) interface.
        !            20: .PP
        !            21: The information contained herein is skeletal:
        !            22: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
        !            23: clients are coded and interact with the \fIlibrtsap\fR library.
        !            24: .SH ADDRESSES
        !            25: RtSAP addresses are represented by the \fBRtSAPaddr\fR structure.
        !            26: This contains a session address,
        !            27: and the port number of the RtSAP as found in the \fIisoservices\fR\0(5)
        !            28: database.
        !            29: .SH "SERVER INITIALIZATION"
        !            30: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
        !            31: with the argument vector listed in the ISODE services database.
        !            32: The server's very first action is to re\-capture the RtSAP state as
        !            33: recorded by \fItsapd\fR.
        !            34: This is accomplished by calling \fBRtBInit\fR.
        !            35: Information returned by this call is equivalent to the parameters passed by
        !            36: the X.410 OPEN.INDICATION event.
        !            37: If the call is successful,
        !            38: the program can then examine the argument vector that was passed via
        !            39: \fIexecvp\fR
        !            40: (it's important to call \fBRtBInit\fR prior to reading \fBargc\fR and
        !            41: \fBargv\fR).
        !            42: If the call to \fBRtBInit\fR is not successful,
        !            43: information returned by the call indicates the reason for failure.
        !            44: .PP
        !            45: After examining the information provided by \fBRtBInit\fR
        !            46: (and possibly the argument vector),
        !            47: the server should either accept or reject the association.
        !            48: If accepting, the \fBRtBeginResponse\fR routine is called with the parameter
        !            49: \fBstatus\fR set to
        !            50: .sp
        !            51: .in +.5i
        !            52: .nf
        !            53: .ta \w'RTS_VALIDATE  'u
        !            54: RTS_ACCEPT     association accepted
        !            55: .re
        !            56: .fi
        !            57: .in -.5i
        !            58: .sp
        !            59: (which corresponds to the accepting RT\-BEGIN.RESPONSE action).
        !            60: If the call is successful,
        !            61: the association has been bound.
        !            62: If un\-successful,
        !            63: information returned by the call indicates the reason for failure.
        !            64: If rejecting, the \fBRtBeginResponse\fR routine is also called,
        !            65: but with the parameter \fBstatus\fR set to one of:
        !            66: .sp
        !            67: .in +.5i
        !            68: .nf
        !            69: .ta \w'RTS_VALIDATE  'u
        !            70: RTS_BUSY       busy
        !            71: RTS_RECOVER    cannot recover
        !            72: RTS_VALIDATE   validation failure
        !            73: RTS_MODE       unacceptable dialogue mode
        !            74: .re
        !            75: .fi
        !            76: .in -.5i
        !            77: .sp
        !            78: (which corresponds to the refusing X.410 OPEN.RESPONSE action),
        !            79: and the program may exit.
        !            80: .SH "CLIENT INITIALIZATION"
        !            81: A program requesting an ISO service calls \fBRtBeginRequest\fR
        !            82: (which corresponds to the X.410 OPEN.REQUEST action).
        !            83: If successful (depending on the responder's choice of \fBstatus\fR),
        !            84: the association is bound.
        !            85: If un\-successful,
        !            86: information returned by the call indicates the reason for failure.
        !            87: .SH ASSOCIATION\-DESCRIPTORS
        !            88: Once an association has been bound via a successful return from
        !            89: \fBRtBeginResponse\fR (for servers) or \fBRtBeginRequest\fR (for clients),
        !            90: an association is referenced by a small integer
        !            91: (returned in a structure passed to these calls) called an
        !            92: \fIassociation\-descriptor\fR.
        !            93: The association\-descriptor appears as an argument to the peer routines
        !            94: described below.
        !            95: .PP
        !            96: By default,
        !            97: events associated with a association\-descriptor are synchronous in nature:
        !            98: activity in the network won't generate an INDICATION event without program
        !            99: first asking to be told of any activity.
        !           100: To mark an association\-descriptor as asynchronous,
        !           101: a call to \fBRtSetIndications\fR is made with the address of an integer
        !           102: function to handle incoming events.
        !           103: Upon a successful return from \fBRtSetIndications\fR,
        !           104: the event handler will be called in this fashion:
        !           105: .sp
        !           106: .in +.5i
        !           107: .B "(*handler) (sd, rti);"
        !           108: .in -.5i
        !           109: .sp
        !           110: where \fBsd\fR is the association\-descriptor,
        !           111: and \fBrti\fR is a pointer to a \fBRtSAPindication\fR structure.
        !           112: Any value returned by the event\-handler is ignored.
        !           113: .PP
        !           114: Note well: the \fB\-lisode\fR library uses the \fB\-ltsap\fR library to
        !           115: provide this interface.
        !           116: The latter library  uses the SIGEMT signal to provide this service.
        !           117: Programs loaded with \fB\-ltsap\fR that use asynchronous
        !           118: association\-descriptors should NOT use SIGEMT for other purposes.
        !           119: .PP
        !           120: For synchronous multiplexing of several associations,
        !           121: the routine \fBRtSelectMask\fR
        !           122: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
        !           123: .SH PEER
        !           124: A fatal failure (consult the \fIUser's Manual\fR)
        !           125: on return from any of these routines results in the association being unbound.
        !           126: .sp
        !           127: .in +.5i
        !           128: .nf
        !           129: .ta \w'\fBRtTransferRequest\fR  'u
        !           130: \fIroutine\fR  \fIaction\fR
        !           131: \fBRtPTurnRequest\fR   RT\-TURN\-PLEASE.REQUEST
        !           132: \fBRtGTurnRequest\fR   RT\-TURN\-GIVE.REQUEST
        !           133: \fBRtTransferRequest\fR        RT\-TRANSFER.REQUEST
        !           134: \fBRtWaitRequest\fR    RT\-WAIT.REQUEST (synchronous wait)
        !           135: \fBRtEndRequest\fR     X.410 CLOSE.REQUEST
        !           136: \fBRtEndResponse\fR    X.410 CLOSE.RESPONSE
        !           137: .re
        !           138: .fi
        !           139: .in -.5i
        !           140: .sp
        !           141: Note that the \fBRtWaitRequest\fR routine returns data from the peer by
        !           142: allocating memory.
        !           143: It should be freed before the structure is re\-used.
        !           144: .PP
        !           145: Finally,
        !           146: the routine \fBRtErrString\fR takes a failure code from a \fBRtSAPabort\fR
        !           147: structure and returns a null\-terminated diagnostic string.
        !           148: .SH FILES
        !           149: .nf
        !           150: .ta \w'\*(EDisoservices  'u
        !           151: \*(EDisoentities       ISODE entities database
        !           152: \*(EDisobjects ISODE objects database
        !           153: \*(EDisoservices       ISODE services database
        !           154: .re
        !           155: .fi
        !           156: .SH "SEE ALSO"
        !           157: libacsap(3n), librosap (3n), isoentities(5), isobjects (5), isoservices(5)
        !           158: .br
        !           159: \fIThe ISO Development Environment: User's Manual\fR,
        !           160: .br
        !           161: ISO DIS 9066/1:
        !           162: \fIInformation Processing Systems \-\- Text Communication \-\- MOTIS \-\-
        !           163: Reliable Transfer Part 1: Model and Service Definition\fR,
        !           164: .br 
        !           165: CCITT Recommendation X.410:
        !           166: \fIMessage Handling Systems: Remote Operations and Reliable Transfer Server\fR
        !           167: .SH DIAGNOSTICS
        !           168: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
        !           169: .SH AUTHORS
        !           170: Marshall T. Rose,
        !           171: The Wollongong Group
        !           172: .SH BUGS
        !           173: Do not confuse association\-descriptors with file\-descriptors.
        !           174: Unlike file\-descriptors which are implemented by the kernel,
        !           175: association\-descriptors to 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.