Return to libssap.3n CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/ssap/libssap.3n, revision 1.1

1.1     ! root        1: .TH LIBSSAP 3N "31 May 1988"
        !             2: .\" $Header: /f/osi/ssap/RCS/libssap.3n,v 7.0 89/11/23 22:25:17 mrose Rel $
        !             3: .\"
        !             4: .\"
        !             5: .\" $Log:      libssap.3n,v $
        !             6: .\" Revision 7.0  89/11/23  22:25:17  mrose
        !             7: .\" Release 6.0
        !             8: .\" 
        !             9: .SH NAME
        !            10: libssap \- Session Services library
        !            11: .SH SYNOPSIS
        !            12: .B "#include <isode/ssap.h>"
        !            13: .sp
        !            14: \fIcc\fR\0...\0\fB\-lssap\fR
        !            15: .SH DESCRIPTION
        !            16: The \fIlibssap\fR library contains a set of routines which implement
        !            17: session services.
        !            18: In essence,
        !            19: they implement an Session Service Access Point (SSAP) interface for user
        !            20: applications.
        !            21: This manual page describes only the interface to the Basic Combined Subset
        !            22: (BCS) of session;
        !            23: consult the \fIUser's Manual\fR for the full details on the entire SSAP
        !            24: interface.
        !            25: .PP
        !            26: Although the ISO model is symmetric,
        !            27: this implementation is based on a client/server paradigm and hence asymmetric.
        !            28: The information herein is skeletal:
        !            29: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
        !            30: clients are coded and interact with the \fIlibssap\fR library.
        !            31: .SH ADDRESSES
        !            32: SSAP addresses are represented by the \fBSSAPaddr\fR structure.
        !            33: This contains a transport address,
        !            34: and a session-selector as found in the \fIisoservices\fR\0(5)
        !            35: database.
        !            36: .PP
        !            37: SSAP references,
        !            38: represented by the \fBSSAPref\fR structure,
        !            39: consist of three attributes:
        !            40: the user reference, the common reference, and the additional reference.
        !            41: These are preserved by the SSAP but otherwise ignored.
        !            42: .SH "SERVER INITIALIZATION"
        !            43: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
        !            44: with the argument vector listed in the ISODE services database.
        !            45: The server's very first action is to re\-capture the SSAP state as
        !            46: recorded by \fItsapd\fR.
        !            47: This is accomplished by calling \fBSInit\fR.
        !            48: Information returned by this call is equivalent to the parameters passed by a
        !            49: S\-CONNECTION.INDICATION event.
        !            50: If the call is successful,
        !            51: the program can then examine the argument vector that was passed via
        !            52: \fIexecvp\fR
        !            53: (it's important to call \fBSInit\fR prior to reading \fBargc\fR and
        !            54: \fBargv\fR).
        !            55: If the call to \fBSInit\fR is not successful,
        !            56: information returned by the call indicates the reason for failure.
        !            57: .PP
        !            58: After examining the information provided by \fBSInit\fR
        !            59: (and possibly the argument vector),
        !            60: the server should either accept or reject the connection.
        !            61: If accepting, the \fBSConnResponse\fR routine is called with the parameter
        !            62: \fBresult\fR set to
        !            63: .sp
        !            64: .in +.5i
        !            65: .nf
        !            66: .ta \w'SC_NOTSPECIFIED  'u
        !            67: SC_ACCEPT      connection accepted
        !            68: .re
        !            69: .fi
        !            70: .in -.5i
        !            71: .sp
        !            72: (which corresponds to the accepting S\-CONNECT.RESPONSE action).
        !            73: If the call is successful,
        !            74: the interaction is henceforth symmetric.
        !            75: If un\-successful,
        !            76: information returned by the call indicates the reason for failure.
        !            77: If rejecting, the \fBSConnResponse\fR routine is also called,
        !            78: but with the parameter \fBresult\fR set to one of:
        !            79: .sp
        !            80: .in +.5i
        !            81: .nf
        !            82: .ta \w'SC_NOTSPECIFIED  'u
        !            83: SC_NOTSPECIFIED        reason not specified
        !            84: SC_CONGESTION  temporary congestion
        !            85: SC_REJECTED    rejected
        !            86: .re
        !            87: .fi
        !            88: .in -.5i
        !            89: .sp
        !            90: (which corresponds to the refusing S\-CONNECT.RESPONSE action),
        !            91: and the program may exit.
        !            92: .SH "CLIENT INITIALIZATION"
        !            93: A program requesting an ISO service calls \fBSConnRequest\fR
        !            94: (which corresponds to the S\-CONNECT.REQUEST action).
        !            95: If successful (depending on the responder's choice of \fBresult\fR),
        !            96: the interaction is henceforth symmetric.
        !            97: If un\-successful,
        !            98: information returned by the call indicates the reason for failure.
        !            99: .SH SESSION\-DESCRIPTORS
        !           100: Once a connection has been established via a successful return from
        !           101: \fBSConnResponse\fR (for servers) or \fBSConnRequest\fR (for clients),
        !           102: a connection is referenced by a small integer
        !           103: (returned in a structure passed to these calls) called a
        !           104: \fIsession\-descriptor\fR.
        !           105: The session\-descriptor appears as an argument to the peer routines described
        !           106: below.
        !           107: .PP
        !           108: By default,
        !           109: events associated with a session\-descriptor are synchronous in nature:
        !           110: activity in the network won't generate an INDICATION event without program
        !           111: first asking to be told of any activity.
        !           112: To mark a session\-descriptor as asynchronous,
        !           113: a call to \fBSSetIndications\fR is made with the addresses of an integer
        !           114: function to handle these events:
        !           115: .sp
        !           116: .in +.5i
        !           117: .nf
        !           118: .ta \w'\fIroutine\fR  'u
        !           119: \fIroutine\fR  \fIevents\fR
        !           120: \fBfunc1\fR    data
        !           121: \fBfunc2\fR    tokens
        !           122: \fBfunc3\fR    synchronization
        !           123: \fBfunc4\fR    activities
        !           124: \fBfunc5\fR    reports
        !           125: \fBfunc6\fR    release
        !           126: \fBfunc7\fR    aborts
        !           127: .re
        !           128: .fi
        !           129: .in -.5i
        !           130: .sp
        !           131: Upon a successful return from \fBSSetIndications\fR,
        !           132: these functions will be called as appropriate in this fashion:
        !           133: .sp
        !           134: .in +.5i
        !           135: .B "(*func1) (sd, sx);"
        !           136: .sp
        !           137: .B "(*func2) (sd, st);"
        !           138: .sp
        !           139: .B "(*func3) (sd, sn);"
        !           140: .sp
        !           141: .B "(*func4) (sd, sv);"
        !           142: .sp
        !           143: .B "(*func5) (sd, sp);"
        !           144: .sp
        !           145: .B "(*func6) (sd, sf);"
        !           146: .sp
        !           147: .B "(*func7) (sd, sa);"
        !           148: .in -.5i
        !           149: .sp
        !           150: where \fBsd\fR is the session\-descriptor,
        !           151: \fBsx\fR is a pointer to a \fBSSAPdata\fR structure,
        !           152: \fBst\fR is a pointer to a \fBSSAPtoken\fR structure,
        !           153: \fBsn\fR is a pointer to a \fBSSAPsync\fR structure,
        !           154: \fBsv\fR is a pointer to a \fBSSAPactivity\fR structure,
        !           155: \fBsp\fR is a pointer to a \fBSSAPreport\fR structure,
        !           156: \fBsf\fR is a pointer to a \fBSSAPfinish\fR structure,
        !           157: and \fBsa\fR is a pointer to a \fBSSAPabort\fR structure.
        !           158: Any value returned by these functions is ignored.
        !           159: .PP
        !           160: Note well: the \fB\-lssap\fR library uses the \fB\-ltsap\fR library to
        !           161: provide this interface.
        !           162: The latter library  uses the SIGEMT signal to provide this service.
        !           163: Programs loaded with \fB\-ltsap\fR that use asynchronous session\-descriptors
        !           164: should NOT use SIGEMT for other purposes.
        !           165: .PP
        !           166: For synchronous multiplexing of several connections,
        !           167: the routine \fBSSelectMask\fR
        !           168: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
        !           169: .SH PEER
        !           170: A fatal failure (consult the \fIUser's Manual\fR)
        !           171: on return from any of these routines is equivalent to a
        !           172: S\-P\-ABORT.INDICATION.
        !           173: .sp
        !           174: .in +.5i
        !           175: .nf
        !           176: .ta \w'\fBSUAbortRequest\fR  'u
        !           177: \fIroutine\fR  \fIaction\fR
        !           178: \fBSDataRequest\fR     S\-DATA.REQUEST
        !           179: \fBSExpdRequest\fR     S\-EXPEDITED\-DATA.REQUEST
        !           180: \fBSReadRequest\fR     S\-READ.REQUEST (synchronous read)
        !           181: \fBSGTokenRequest\fR   S\-TOKEN\-GIVE.REQUEST
        !           182: \fBSPTokenRequest\fR   S\-TOKEN\-PLEASE.REQUEST
        !           183: \fBSRelRequest\fR      S\-RELEASE.REQUEST
        !           184: \fBSRelResponse\fR     S\-RELEASE.RESPONSE
        !           185: \fBSUAabortRequest\fR  S\-U\-ABORT.REQUEST
        !           186: .re
        !           187: .fi
        !           188: .in -.5i
        !           189: .sp
        !           190: Note that the \fBSReadRequest\fR routine returns data from the peer by
        !           191: allocating memory.
        !           192: It should be freed before the structure is re\-used.
        !           193: .PP
        !           194: Also note that session utilizes a graceful closing mechanism.
        !           195: Upon receipt of a S\-RELEASE\-INDICATION event,
        !           196: the peer must immediately respond with an S\-RELEASE\-RESPONSE.
        !           197: Depending on the setting of the session requirements (described next),
        !           198: the peer may indicate refusal in the response.
        !           199: .PP
        !           200: Finally,
        !           201: the routine \fBSErrString\fR takes a failure code from a \fBSSAPabort\fR
        !           202: structure and returns a null\-terminated diagnostic string.
        !           203: Also,
        !           204: the routine \fBSLocalHostName\fR returns a null\-terminated string denoting
        !           205: the name of the localhost;
        !           206: .SH "SESSION REQUIREMENTS"
        !           207: During the connection\-establishment phase,
        !           208: the session\-users and session\-providers negotiate the characteristics of
        !           209: the connection.
        !           210: In particular,
        !           211: they negotiate the \*(lqsession requirements\*(rq.
        !           212: These requirements describe functional aspects of the connection,
        !           213: and are always negotiated downwards.
        !           214: primitives.
        !           215: .SH FILES
        !           216: .nf
        !           217: .ta \w'\*(EDisoservices  'u
        !           218: \*(EDisoservices       ISODE services database
        !           219: .re
        !           220: .fi
        !           221: .SH "SEE ALSO"
        !           222: isoservices(5), tsapd(8c),
        !           223: .br
        !           224: \fIThe ISO Development Environment: User's Manual\fR,
        !           225: .br
        !           226: ISO 8326:
        !           227: \fIInformation Processing Systems \-\- Open Systems Interconnection~---~
        !           228: Connection Oriented Session Service Definition\fR,
        !           229: .br
        !           230: CCITT Recommendation X.215:
        !           231: \fISession Service Definition for Open Systems Interconnection (OSI) for
        !           232: CCITT Applications\fR
        !           233: .SH DIAGNOSTICS
        !           234: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
        !           235: In addition,
        !           236: those routines which take a pointer to a \fBSSAPindication\fR structure
        !           237: fill\-in the structure as appropriate.
        !           238: .SH AUTHORS
        !           239: Marshall T. Rose
        !           240: .br
        !           241: Dwight E. Cass,
        !           242: Northrop Research and Technology Center
        !           243: .SH BUGS
        !           244: Do not confuse session\-descriptors with file\-descriptors.
        !           245: Unlike file\-descriptors which are implemented by the kernel,
        !           246: session\-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.