Return to libpsap.3 CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/psap/libpsap.3, revision 1.1

1.1     ! root        1: .TH LIBPSAP 3 "15 APR 1986"
        !             2: .\" $header: /f/iso/psap/rcs/libpsap.3,v 4.4 88/05/31 15:19:26 mrose exp $
        !             3: .\"
        !             4: .\"
        !             5: .\" $log:      libpsap.3,v $
        !             6: .\" revision 4.4  88/05/31  15:19:26  mrose
        !             7: .\" 3n -> 3
        !             8: .\" 
        !             9: .\" revision 4.3  88/05/30  18:30:52  mrose
        !            10: .\" update
        !            11: .\" 
        !            12: .\" revision 4.2  88/01/29  14:55:14  mrose
        !            13: .\" touch-up
        !            14: .\" 
        !            15: .\" revision 4.1  87/12/28  13:35:24  mrose
        !            16: .\" twg
        !            17: .\" 
        !            18: .\" revision 4.0  87/10/12  16:19:59  mrose
        !            19: .\" release 3.0
        !            20: .\" 
        !            21: .SH NAME
        !            22: libpsap \- asn.1 presentation services library
        !            23: .SH SYNOPSIS
        !            24: .B "#include <isode/psap.h>"
        !            25: .sp
        !            26: \fIcc\fR\0...\0\fB\-lpsap\fR
        !            27: .SH DESCRIPTION
        !            28: the \fIlibpsap\fR library contains a set of routines which implement
        !            29: presentation syntax abstractions.
        !            30: two primary objects are manipulated:
        !            31: presentation \fIelements\fR and presentation \fIstreams\fR.
        !            32: .SH "PRESENTATION STREAMS"
        !            33: a stream is an object, similar to a \fBfile*\fR object in \fIstdio\fR\0(3),
        !            34: which is used to read and write elements.
        !            35: a stream is created by calling \fBps_alloc\fR with the address of an
        !            36: integer\-valued routine that will initialize certain stream\-dependent
        !            37: variables (presently, the read and write routines).
        !            38: two standard initialization routines are available:
        !            39: \fBstd_open\fR,
        !            40: which is used for presentation streams connected to \fIstdio\fR objects;
        !            41: and,
        !            42: \fBstr_open\fR,
        !            43: which is used for presentation streams connected to \fIstring\fR objects.
        !            44: after \fBps_alloc\fR successfully returns,
        !            45: final initialization is performed,
        !            46: usually by calling either
        !            47: \fBstd_setup\fR with the \fIstdio\fR object to be bound;
        !            48: or,
        !            49: \fBstr_setup\fR with the string object to be bound.
        !            50: after the setup routine successfully returns,
        !            51: the presentation stream is ready for reading or writing.
        !            52: .PP
        !            53: currently streams which have been initialized by these routines are
        !            54: uni-directional.
        !            55: This might change in a future distribution.
        !            56: Streams which have been initialized by \fBstd_open\fR and \fBstr_open\fR
        !            57: will automatically allocate additional resources when necessary,
        !            58: to the limits allowed by the operating system
        !            59: (e.g., repeated calls to a stream connected to a \fIstring\fR object will
        !            60: result in additional memory being allocated from UNIX).
        !            61: .PP
        !            62: Low\-level I/O is done from/to the stream by the macros \fBps_read\fR and
        !            63: \fBps_write\fR.
        !            64: These both call an internal routine which switches to the object\-specific
        !            65: read or write routine as appropriate.
        !            66: This internal routine, \fBps_io\fR, implements the consistent presentation
        !            67: stream abstraction.
        !            68: .PP
        !            69: Finally,
        !            70: when a stream has been exhausted, 
        !            71: it can be closed and de\-allocated with \fBps_free\fR.
        !            72: .PP
        !            73: The user may implement additional stream objects.
        !            74: Examine the source to the \fBstd_\fR and \fBstr_\fR routines
        !            75: to understand the internal protocol and uniform interface.
        !            76: .SH TRANSLATION
        !            77: The routine \fBps2pe\fR can be used to read the next presentation element
        !            78: from a stream.
        !            79: This routine returns a pointer to the element or \fBNULLPE\fR on error.
        !            80: Similarly, \fBpe2ps\fR can be used to write a presentation element at the end
        !            81: of the stream.
        !            82: This returns returns \fBOK\fR if all went well, \fBNOTOK\fR otherwise.
        !            83: On errors with either routine,
        !            84: the \fBps_errno\fR field of the stream can be consulted to see what happened.
        !            85: .PP
        !            86: When writing to a presentation stream,
        !            87: the variable \fBps_len_strategy\fR controls how long CONStructor types are
        !            88: represented.
        !            89: If this variable is equal to \fBPS_LEN_SPAG\fR (the default),
        !            90: then the indefinite form is used whenever the length field of the element can
        !            91: not be represented in one octet.
        !            92: If \fBPS_LEN_INDF\fR,
        !            93: then the indefinite form is used regardless of the length of the element.
        !            94: Otherwise,
        !            95: if \fBPS_LEN_LONG\fR,
        !            96: then the indefinite form is never used.
        !            97: .PP
        !            98: For debugging purposes,
        !            99: instead of treating a presentation stream as a binary object,
        !           100: the routines \fBpl2pe\fR and \fBpe2pl\fR can be used.
        !           101: These translate between presentation \fIlists\fR and presentation elements.
        !           102: A list is an ASCII text representation,
        !           103: with a simple LISP\-like syntax which contains semantic information
        !           104: identical to its presentation stream counterpart.
        !           105: .SH "PRESENTATION ELEMENTS"
        !           106: Once a presentation stream has been initialized and elements are being read,
        !           107: there are several routines that can be used to translate between the
        !           108: machine\-independent representation of the element and machine\-specific
        !           109: objects such as integers, strings, and the like.
        !           110: It is extremely important that programs use these routines to perform the
        !           111: translation between objects.
        !           112: They have been carefully coded to present a simple, uniform interface between
        !           113: machine\-specifics and the machine\-independent presentation protocol.
        !           114: .PP
        !           115: A new element can be created with \fBpe_alloc\fR,
        !           116: and de\-allocated with \fBpe_free\fR
        !           117: (see the warning in the \fBBUGS\fR section below).
        !           118: Two elements can be compared with \fBpe_cmp\fR,
        !           119: and an element can be copied with \fBpe_cpy\fR.
        !           120: .PP
        !           121: A \fIboolean\fR is an integer taking on the values \fB0\fR or \fB1\fR.
        !           122: The routine \fBprim2bool\fR takes an element and returns the boolean value
        !           123: encoded therein.
        !           124: Similarly, \fBbool2prim\fR takes a boolean and returns an element which
        !           125: encodes that value.
        !           126: .PP
        !           127: An \fIinteger\fR is a signed\-quantity, whose precision is specific to a
        !           128: particular host.
        !           129: The routine \fBprim2int\fR takes an element and returns the integer value
        !           130: encoded therein (if the value is \fBNOTOK\fR, check the \fBpe_errno\fR field
        !           131: of the element to see if there was an error).
        !           132: The routine \fBint2prim\fR performs the inverse operation.
        !           133: .PP
        !           134: An \fIoctetstring\fR is a pair of values,
        !           135: a character pointer and an integer length.
        !           136: The pointer addresses the first octet in the string
        !           137: (which need not be null\-terminated),
        !           138: the length indicates how many octets are in the string.
        !           139: The routine \fBprim2oct\fR takes an element and allocates a new string
        !           140: containing the value encoded therein.
        !           141: The routine \fBoct2prim\fR performs the inverse operation,
        !           142: copying the original string (and not de\-allocating it).
        !           143: .PP
        !           144: A \fIbitvector\fR is an arbitrarily long string of bits with three operations:
        !           145: \fBbit_on\fR which turns the indicated bit on,
        !           146: \fBbit_off\fR which turns the indicated bit off,
        !           147: and,
        !           148: \fBbit_test\fR which returns a boolean value telling if the indicated bit was
        !           149: on.
        !           150: The routine \fBprim2bit\fR takes an element and builds such an abstraction
        !           151: containing the value encoded therein.
        !           152: The routine \fBbit2prim\fR performs the inverse operation.
        !           153: .PP
        !           154: A \fItimestring\fR represents a date/time in many forms.
        !           155: Consult \fB<isode/psap.h>\fR for the elements in this structure.
        !           156: The routines \fBprim2utc\fR and \fButc2prim\fR are used to translate between
        !           157: a machine\-specific internal form and the machine\-independent form.
        !           158: .PP
        !           159: Two list disciplines are implemented:
        !           160: \fIsets\fR, in which each member is distinguished by a unique identifier;
        !           161: and,
        !           162: \fIsequences\fR, in which each element is distinguished by its offset from
        !           163: the head of the list.
        !           164: On both types of lists,
        !           165: the macro \fBfirst_member\fR returns the first member in the list,
        !           166: while \fBnext_member\fR returns the next member.
        !           167: .PP
        !           168: The routines \fBprim2set\fR and \fBset2prim\fR are used to translate between
        !           169: presentation elements and the set list;
        !           170: \fBset_add\fR may be called to add a new member to the set;
        !           171: \fBset_del\fR may be called to remove the identified member from the set;
        !           172: and,
        !           173: \fBset_find\fR may be called to locate the identified member.
        !           174: .PP
        !           175: The routines \fBprim2seq\fR and \fBseq2prim\fR are used to translate between
        !           176: presentation elements and the sequence list;
        !           177: \fBseq_add\fR may be called to add a new element to the sequence;
        !           178: \fBseq_del\fR may be called to remove the identified element from the sequence;
        !           179: and,
        !           180: \fBseq_find\fR may be called to locate the identified element.
        !           181: .PP
        !           182: With both lists,
        !           183: a convenient way of stepping through all the members is:
        !           184: .sp
        !           185: .in +.5i
        !           186: .nf
        !           187: .B "for (p = first_member (pe); p; p = next_member (pe, p))"
        !           188: .B "\0\0\0\0switch (\fIdiscriminator\fR) {"
        !           189: .B "\0\0\0\0\0\0\0\0...."
        !           190: .B "\0\0\0\0}"
        !           191: .fi
        !           192: .in -.5i
        !           193: .sp
        !           194: where \fIdiscriminator\fR is:
        !           195: .sp
        !           196: .in +.5i
        !           197: .B "PE_ID (p \-> pe_class, p \-> pe_id)"
        !           198: .in -.5i
        !           199: .sp
        !           200: for sets,
        !           201: and:
        !           202: .sp
        !           203: .in +.5i
        !           204: .B "p \-> pe_offset"
        !           205: .in -.5i
        !           206: .sp
        !           207: for sequences.
        !           208: .SH FILES
        !           209: None
        !           210: .SH "SEE ALSO"
        !           211: pepy(1),
        !           212: .br
        !           213: \fIThe ISO Development Environment: User's Manual\fR,
        !           214: .br
        !           215: ISO 8825:
        !           216: \fIInformation Processing \-\- Open Systems
        !           217: Interconnection \-\- Specification of basic encoding rules for Abstract Syntax
        !           218: Notation One (ASN.1)\fR,
        !           219: .br
        !           220: CCITT Recommendation X.409:
        !           221: \fIMessage Handling Systems:
        !           222: Presentation Transfer Syntax and Notation\fR
        !           223: .SH DIAGNOSTICS
        !           224: Most routines either return the manifest constant \fBNULL\fR (0) or
        !           225: \fBNOTOK\fR (\-1) on error.
        !           226: In addition,
        !           227: routines called with a pointer to a presentation stream also update the
        !           228: \fBps_errno\fR field of the stream on error.
        !           229: The routine \fBps_error\fR returns a null\-termianted diagnostic string when
        !           230: given the value of this field.
        !           231: Similarly,
        !           232: routines called with a pointer to a presentation element also update the
        !           233: \fBpe_errno\fR field of the stream on error.
        !           234: The routine \fBpe_error\fR returns a null\-termianted diagnostic string when
        !           235: given the value of this field.
        !           236: .SH AUTHOR
        !           237: Marshall T. Rose
        !           238: .SH BUGS
        !           239: A \*(lqvirtual\*(rq presentation element option should be available to avoid
        !           240: reading everything in\-core during parsing.
        !           241: .PP
        !           242: When using \fBpe_free\fR on an element,
        !           243: care must be taken to remove any references to that element in other
        !           244: structures.
        !           245: For example,
        !           246: if you have a sequence containing a sequence,
        !           247: and you free the child sequence,
        !           248: be sure to zero\-out the parent's pointer to the child,
        !           249: otherwise subsequent calls using the parent will go romping through
        !           250: hyperspace.
        !           251: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.