![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libpsap.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / psap|
Return to libpsap.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / psap |
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.