Return to libpsap2.3n CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/psap2/libpsap2.3n, revision 1.1

1.1     ! root        1: .TH LIBPSAP2 3N "31 May 1988"
        !             2: .\" $Header: /f/osi/psap2/RCS/libpsap2.3n,v 7.0 89/11/23 22:14:11 mrose Rel $
        !             3: .\"
        !             4: .\"
        !             5: .\" $Log:      libpsap2.3n,v $
        !             6: .\" Revision 7.0  89/11/23  22:14:11  mrose
        !             7: .\" Release 6.0
        !             8: .\" 
        !             9: .SH NAME
        !            10: libpsap2 \- Presentation Services library
        !            11: .SH SYNOPSIS
        !            12: .B "#include <isode/psap2.h>"
        !            13: .sp
        !            14: \fIcc\fR\0...\0\fB\-lpsap2\fR
        !            15: .SH DESCRIPTION
        !            16: The \fIlibpsap2\fR library contains a set of routines which implement the
        !            17: presentation services.
        !            18: In essence,
        !            19: they implement a Presentation Service Access Point (PSAP) interface for
        !            20: user applications.
        !            21: This manual page describes only the interface to the Basic Combined Subset
        !            22: (BCS) of session which is available for presentation;
        !            23: consult the \fIUser's Manual\fR for the full details on the entire PSAP
        !            24: interface, which supports the entire presentation service.
        !            25: Note well:
        !            26: before using presentation services,
        !            27: an understanding of the underlying session services is necessary.
        !            28: .PP
        !            29: Although the ISO model is symmetric,
        !            30: this implementation is based on a client/server paradigm and hence asymmetric.
        !            31: The information herein is skeletal:
        !            32: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
        !            33: clients are coded and interact with the \fIlibpsap2\fR library.
        !            34: .SH ADDRESSES
        !            35: PSAP addresses are represented by the \fBPSAPaddr\fR structure.
        !            36: This contains a session address,
        !            37: and a presentation-selector as found in the \fIisoservices\fR\0(5)
        !            38: database.
        !            39: .SH "SERVER INITIALIZATION"
        !            40: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
        !            41: with the argument vector listed in the ISODE services database.
        !            42: The server's very first action is to re\-capture the PSAP state as
        !            43: recorded by \fItsapd\fR.
        !            44: This is accomplished by calling \fBPInit\fR.
        !            45: Information returned by this call is equivalent to the parameters passed by a
        !            46: P\-CONNECTION.INDICATION event.
        !            47: If the call is successful,
        !            48: the program can then examine the argument vector that was passed via
        !            49: \fIexecvp\fR
        !            50: (it's important to call \fBPInit\fR prior to reading \fBargc\fR and
        !            51: \fBargv\fR).
        !            52: If the call to \fBPInit\fR is not successful,
        !            53: information returned by the call indicates the reason for failure.
        !            54: .PP
        !            55: After examining the information provided by \fBPInit\fR
        !            56: (and possibly the argument vector),
        !            57: the server should either accept or reject the connection.
        !            58: If accepting, the \fBPConnResponse\fR routine is called with the parameter
        !            59: \fBresult\fR set to \fBPC_ACCEPT\fR.
        !            60: (which corresponds to the accepting P\-CONNECT.RESPONSE action).
        !            61: If the call is successful,
        !            62: the interaction is henceforth symmetric.
        !            63: If un\-successful,
        !            64: information returned by the call indicates the reason for failure.
        !            65: If rejecting, the \fBPConnResponse\fR routine is also called,
        !            66: but with the parameter \fBresult\fR set to \fBPC_REJECTED\fR.
        !            67: (which corresponds to the refusing P\-CONNECT.RESPONSE action),
        !            68: and the program may exit.
        !            69: .SH "CLIENT INITIALIZATION"
        !            70: A program requesting an ISO service calls \fBPConnRequest\fR
        !            71: (which corresponds to the P\-CONNECT.REQUEST action).
        !            72: If successful (depending on the responder's choice of \fBresult\fR),
        !            73: the interaction is henceforth symmetric.
        !            74: If un\-successful,
        !            75: information returned by the call indicates the reason for failure.
        !            76: .SH PRESENTATION\-DESCRIPTORS
        !            77: Once a connection has been established via a successful return from
        !            78: \fBPConnResponse\fR (for servers) or \fBPConnRequest\fR (for clients),
        !            79: a connection is referenced by a small integer
        !            80: (returned in a structure passed to these calls) called a
        !            81: \fIpresentation\-descriptor\fR.
        !            82: The presentation\-descriptor appears as an argument to the peer routines
        !            83: described below.
        !            84: .PP
        !            85: By default,
        !            86: events associated with a presentation\-descriptor are synchronous in nature:
        !            87: activity in the network won't generate an INDICATION event without program
        !            88: first asking to be told of any activity.
        !            89: To mark a presentation\-descriptor as asynchronous,
        !            90: a call to \fBPSetIndications\fR is made with the addresses of an integer
        !            91: function to handle these events:
        !            92: .sp
        !            93: .in +.5i
        !            94: .nf
        !            95: .ta \w'\fIroutine\fR  'u
        !            96: \fIroutine\fR  \fIevents\fR
        !            97: \fBfunc1\fR    data
        !            98: \fBfunc2\fR    tokens
        !            99: \fBfunc3\fR    synchronization
        !           100: \fBfunc4\fR    activities
        !           101: \fBfunc5\fR    reports
        !           102: \fBfunc6\fR    release
        !           103: \fBfunc7\fR    aborts
        !           104: .re
        !           105: .fi
        !           106: .in -.5i
        !           107: .sp
        !           108: Upon a successful return from \fBPSetIndications\fR,
        !           109: these functions will be called as appropriate in this fashion:
        !           110: .sp
        !           111: .in +.5i
        !           112: .B "(*func1) (sd, px);"
        !           113: .sp
        !           114: .B "(*func2) (sd, pt);"
        !           115: .sp
        !           116: .B "(*func3) (sd, pn);"
        !           117: .sp
        !           118: .B "(*func4) (sd, pv);"
        !           119: .sp
        !           120: .B "(*func5) (sd, pp);"
        !           121: .sp
        !           122: .B "(*func6) (sd, pf);"
        !           123: .sp
        !           124: .B "(*func7) (sd, pa);"
        !           125: .in -.5i
        !           126: .sp
        !           127: where \fBpd\fR is the presentation\-descriptor,
        !           128: \fBpx\fR is a pointer to a \fBPSAPdata\fR structure,
        !           129: \fBpt\fR is a pointer to a \fBPSAPtoken\fR structure,
        !           130: \fBpn\fR is a pointer to a \fBPSAPsync\fR structure,
        !           131: \fBpv\fR is a pointer to a \fBPSAPactivity\fR structure,
        !           132: \fBpp\fR is a pointer to a \fBPSAPreport\fR structure,
        !           133: \fBpf\fR is a pointer to a \fBPSAPfinish\fR structure,
        !           134: and \fBpa\fR is a pointer to a \fBPSAPabort\fR structure.
        !           135: Any value returned by these functions is ignored.
        !           136: .PP
        !           137: Note well: the \fB\-lpsap\fR library uses the \fB\-ltsap\fR library to
        !           138: provide this interface.
        !           139: The latter library  uses the SIGEMT signal to provide this service.
        !           140: Programs loaded with \fB\-ltsap\fR that use asynchronous
        !           141: presentation\-descriptors should NOT use SIGEMT for other purposes.
        !           142: .PP
        !           143: For synchronous multiplexing of several connections,
        !           144: the routine \fBPSelectMask\fR
        !           145: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
        !           146: .SH PEER
        !           147: A fatal failure (consult the \fIUser's Manual\fR)
        !           148: on return from any of these routines is equivalent to a
        !           149: P\-P\-ABORT.INDICATION.
        !           150: .sp
        !           151: .in +.5i
        !           152: .nf
        !           153: .ta \w'\fBPUAbortRequest\fR  'u
        !           154: \fIroutine\fR  \fIaction\fR
        !           155: \fBPDataRequest\fR     P\-DATA.REQUEST
        !           156: \fBPExpdRequest\fR     P\-EXPEDITED\-DATA.REQUEST
        !           157: \fBPReadRequest\fR     P\-READ.REQUEST (synchronous read)
        !           158: \fBPGTokenRequest\fR   P\-TOKEN\-GIVE.REQUEST
        !           159: \fBPPTokenRequest\fR   P\-TOKEN\-PLEASE.REQUEST
        !           160: \fBPRelRequest\fR      P\-RELEASE.REQUEST
        !           161: \fBPRelResponse\fR     P\-RELEASE.RESPONSE
        !           162: \fBPUAabortRequest\fR  P\-U\-ABORT.REQUEST
        !           163: .re
        !           164: .fi
        !           165: .in -.5i
        !           166: .sp
        !           167: Note that the \fBPReadRequest\fR routine returns data from the peer by
        !           168: allocating memory.
        !           169: It should be freed before the structure is re\-used.
        !           170: .PP
        !           171: Also note that presentation utilizes a graceful closing mechanism.
        !           172: Upon receipt of a P\-RELEASE\-INDICATION event,
        !           173: the peer must immediately respond with an P\-RELEASE\-RESPONSE.
        !           174: Depending on the setting of the session requirements (described next),
        !           175: the peer may indicate refusal in the response.
        !           176: .PP
        !           177: Finally,
        !           178: the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
        !           179: structure and returns a null\-terminated diagnostic string.
        !           180: Also,
        !           181: the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
        !           182: the name of the localhost;
        !           183: .SH "SESSION REQUIREMENTS"
        !           184: During the connection\-establishment phase,
        !           185: the presentation\-users, presentation\-providers, and session\-providers
        !           186: negotiate the characteristics of the connection.
        !           187: In particular,
        !           188: they negotiate the \*(lqsession requirements\*(rq.
        !           189: These requirements describe functional aspects of the connection,
        !           190: and are always negotiated downwards.
        !           191: .SH FILES
        !           192: .nf
        !           193: .ta \w'\*(EDisoservices  'u
        !           194: \*(EDisobjects ISODE objects database
        !           195: \*(EDisoservices       ISODE services database
        !           196: .re
        !           197: .fi
        !           198: .SH "SEE ALSO"
        !           199: isobjects(5), isoservices(5), tsapd(8c),
        !           200: .br
        !           201: \fIThe ISO Development Environment: User's Manual\fR,
        !           202: .br
        !           203: ISO 8822:
        !           204: \fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
        !           205: Connection Oriented Presentation Service Definition\fR
        !           206: .SH DIAGNOSTICS
        !           207: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
        !           208: In addition,
        !           209: those routines which take a pointer to a \fBPSAPindication\fR structure
        !           210: fill\-in the structure as appropriate.
        !           211: .SH AUTHOR
        !           212: Marshall T. Rose
        !           213: .SH BUGS
        !           214: Do not confuse presentation\-descriptors with file\-descriptors.
        !           215: Unlike file\-descriptors which are implemented by the kernel,
        !           216: presentation\-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.