Return to libpsap2-lpp.3n CVS log

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

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

1.1     ! root        1: .TH LIBPSAP2\-LPP 3N "31 May 1988"
        !             2: .\" $Header: /f/osi/psap2-lpp/RCS/libpsap2-lpp.3n,v 7.1 90/07/09 14:44:56 mrose Exp $
        !             3: .\"
        !             4: .\" Contributed by The Wollongong Group, Inc.
        !             5: .\"
        !             6: .\"
        !             7: .\" $Log:      libpsap2-lpp.3n,v $
        !             8: .\" Revision 7.1  90/07/09  14:44:56  mrose
        !             9: .\" sync
        !            10: .\" 
        !            11: .\" Revision 7.0  89/11/23  22:15:47  mrose
        !            12: .\" Release 6.0
        !            13: .\" 
        !            14: .SH NAME
        !            15: libpsap2\-lpp \- (Lightweight) Presentation Services library
        !            16: .SH SYNOPSIS
        !            17: .B "#include <isode/psap2.h>"
        !            18: .sp
        !            19: \fIcc\fR\0...\0\fB\-lpsap2\-lpp\fR
        !            20: .SH DESCRIPTION
        !            21: The \fIlibpsap2\fR library contains a set of routines which implement the
        !            22: presentation services.
        !            23: However,
        !            24: instead of using the ISO presentation protocol,
        !            25: it uses the special lightweight presentation protocol specified in
        !            26: RFC1085.
        !            27: In essence,
        !            28: the library implements a Presentation Service Access Point (PSAP) interface for
        !            29: user applications which utilize only the most minimal set of
        !            30: presentation services.
        !            31: Note well:
        !            32: before using presentation services,
        !            33: an understanding of the underlying session services is necessary.
        !            34: .PP
        !            35: Although the ISO model is symmetric,
        !            36: this implementation is based on a client/server paradigm and hence asymmetric.
        !            37: The information herein is skeletal:
        !            38: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
        !            39: clients are coded and interact with the \fIlibpsap2\-lpp\fR library.
        !            40: .SH ADDRESSES
        !            41: PSAP addresses are represented by the \fBPSAPaddr\fR structure.
        !            42: This contains a session address,
        !            43: and a presentation-selector as found in the \fIisoservices\fR\0(5)
        !            44: database.
        !            45: .SH "SERVER INITIALIZATION"
        !            46: A program providing an ISO service is usually invoked under \fIlppd\fR\0(8c),
        !            47: with the argument vector listed in the ISODE services database.
        !            48: The server's very first action is to re\-capture the PSAP state as
        !            49: recorded by \fIlppd\fR.
        !            50: This is accomplished by calling \fBPInit\fR.
        !            51: Information returned by this call is equivalent to the parameters passed by a
        !            52: P\-CONNECTION.INDICATION event.
        !            53: If the call is successful,
        !            54: the program can then examine the argument vector that was passed via
        !            55: \fIexecvp\fR
        !            56: (it's important to call \fBPInit\fR prior to reading \fBargc\fR and
        !            57: \fBargv\fR).
        !            58: If the call to \fBPInit\fR is not successful,
        !            59: information returned by the call indicates the reason for failure.
        !            60: .PP
        !            61: After examining the information provided by \fBPInit\fR
        !            62: (and possibly the argument vector),
        !            63: the server should either accept or reject the connection.
        !            64: If accepting, the \fBPConnResponse\fR routine is called with the parameter
        !            65: \fBresult\fR set to \fBPC_ACCEPT\fR.
        !            66: (which corresponds to the accepting P\-CONNECT.RESPONSE action).
        !            67: If the call is successful,
        !            68: the interaction is henceforth symmetric.
        !            69: If un\-successful,
        !            70: information returned by the call indicates the reason for failure.
        !            71: If rejecting, the \fBPConnResponse\fR routine is also called,
        !            72: but with the parameter \fBresult\fR set to \fBPC_REJECTED\fR.
        !            73: (which corresponds to the refusing P\-CONNECT.RESPONSE action),
        !            74: and the program may exit.
        !            75: .SH "CLIENT INITIALIZATION"
        !            76: A program requesting an ISO service calls \fBPConnRequest\fR
        !            77: (which corresponds to the P\-CONNECT.REQUEST action).
        !            78: If successful (depending on the responder's choice of \fBresult\fR),
        !            79: the interaction is henceforth symmetric.
        !            80: If un\-successful,
        !            81: information returned by the call indicates the reason for failure.
        !            82: .SH PRESENTATION\-DESCRIPTORS
        !            83: Once a connection has been established via a successful return from
        !            84: \fBPConnResponse\fR (for servers) or \fBPConnRequest\fR (for clients),
        !            85: a connection is referenced by a small integer
        !            86: (returned in a structure passed to these calls) called a
        !            87: \fIpresentation\-descriptor\fR.
        !            88: The presentation\-descriptor appears as an argument to the peer routines
        !            89: described below.
        !            90: .PP
        !            91: For synchronous multiplexing of several connections,
        !            92: the routine \fBPSelectMask\fR
        !            93: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
        !            94: .SH PEER
        !            95: A fatal failure (consult the \fIUser's Manual\fR)
        !            96: on return from any of these routines is equivalent to a
        !            97: P\-P\-ABORT.INDICATION.
        !            98: .sp
        !            99: .in +.5i
        !           100: .nf
        !           101: .ta \w'\fBPUAbortRequest\fR  'u
        !           102: \fIroutine\fR  \fIaction\fR
        !           103: \fBPDataRequest\fR     P\-DATA.REQUEST
        !           104: \fBPReadRequest\fR     P\-READ.REQUEST (synchronous read)
        !           105: \fBPRelRequest\fR      P\-RELEASE.REQUEST
        !           106: \fBPRelResponse\fR     P\-RELEASE.RESPONSE
        !           107: \fBPUAabortRequest\fR  P\-U\-ABORT.REQUEST
        !           108: .re
        !           109: .fi
        !           110: .in -.5i
        !           111: .sp
        !           112: Note that the \fBPReadRequest\fR routine returns data from the peer by
        !           113: allocating memory.
        !           114: It should be freed before the structure is re\-used.
        !           115: .PP
        !           116: Also note that presentation utilizes a graceful closing mechanism.
        !           117: Upon receipt of a P\-RELEASE\-INDICATION event,
        !           118: the peer must immediately respond with an P\-RELEASE\-RESPONSE.
        !           119: Depending on the setting of the session requirements (described next),
        !           120: the peer may indicate refusal in the response.
        !           121: .PP
        !           122: Finally,
        !           123: the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
        !           124: structure and returns a null\-terminated diagnostic string.
        !           125: Also,
        !           126: the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
        !           127: the name of the localhost;
        !           128: .SH FILES
        !           129: .nf
        !           130: .ta \w'\*(EDisoservices  'u
        !           131: \*(EDisobjects ISODE objects database
        !           132: \*(EDisoservices       ISODE services database
        !           133: .re
        !           134: .fi
        !           135: .SH "SEE ALSO"
        !           136: isobjects(5), isoservices(5), tsapd(8c),
        !           137: .br
        !           138: \fIThe ISO Development Environment: User's Manual\fR,
        !           139: .br
        !           140: ISO 8822:
        !           141: \fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
        !           142: Connection Oriented Presentation Service Definition\fR,
        !           143: .br
        !           144: RFC1085:
        !           145: \fIISO Presentation Services on top of TCP/IP\-based internets\fR
        !           146: .SH DIAGNOSTICS
        !           147: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
        !           148: In addition,
        !           149: those routines which take a pointer to a \fBPSAPindication\fR structure
        !           150: fill\-in the structure as appropriate.
        !           151: .SH AUTHOR
        !           152: Marshall T. Rose
        !           153: .SH BUGS
        !           154: Do not confuse presentation\-descriptors with file\-descriptors.
        !           155: Unlike file\-descriptors which are implemented by the kernel,
        !           156: 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.