1 .TH LBER_DECODE 3 "25 January 2002" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int,
7 ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal,
8 ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring,
9 ber_first_element, ber_next_element
10 \- LBER simplified Basic Encoding Rules library routines for decoding
14 .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
16 .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
18 .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
20 .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
22 .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
24 .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
26 .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
28 .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
30 .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
32 .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
34 .BI "ber_tag_t ber_get_null(BerElement *" ber ");"
36 .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
38 .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
40 .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
42 .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
45 These routines provide a subroutine interface to a simplified
46 implementation of the Basic Encoding Rules of ASN.1. The version
47 of BER these routines support is the one defined for the LDAP
48 protocol. The encoding rules are the same as BER, except that
49 only definite form lengths are used, and bitstrings and octet strings
50 are always encoded in primitive form. This man page
51 describes the decoding routines in the lber library. See
53 for details on the corresponding encoding routines.
56 for information about types, allocators, and deallocators.
58 Normally, the only routines that need to be called by an application
61 to get the next BER element and
63 to do the actual decoding. In some cases,
65 may also need to be called in normal usage. The other routines are
66 provided for those applications that need more control than
69 general, these routines return the tag of the element decoded, or
70 LBER_ERROR if an error occurred.
74 routine is used to read the next BER element from the given Sockbuf,
75 \fIsb\fP. It strips off and returns the leading tag, strips off and
76 returns the length of the entire element in \fIlen\fP, and sets up
77 \fIber\fP for subsequent calls to
79 et al to decode the element. See
81 for details of the Sockbuf implementation of the \fIsb\fP parameter.
85 routine is used to decode a BER element in much the same way that
87 works. It reads from \fIber\fP, a pointer to a BerElement
90 interprets the bytes according to the format string \fIfmt\fP, and stores the
91 results in its additional arguments. The format string contains
92 conversion specifications which are used to direct the interpretation
93 of the BER element. The format string can contain the following
99 Octet string. A char ** should be supplied. Memory is allocated,
100 filled with the contents of the octet string, null-terminated, and
101 returned in the parameter. The caller should free the returned
106 Octet string. A char * buffer should be supplied, followed by a pointer to a
107 ber_len_t initialized to the size of the buffer. Upon return, the
108 null-terminated octet string is put into the buffer, and the
109 ber_len_t is set to the actual size of the octet string.
112 Octet string. A struct ber_val ** should be supplied, which upon
113 return points to a dynamically allocated struct berval
114 containing the octet string and its length.
115 The caller should free the returned structure using
119 Octet string. A struct ber_val * should be supplied, which upon
120 return contains the dynamically allocated
121 octet string and its length. The caller should free the returned octet
126 Octet string. A struct ber_val * should be supplied, which upon return
127 contains the octet string and its length. The string resides in memory
128 assigned to the BerElement, and must not be freed by the caller.
131 Boolean. A pointer to a ber_int_t should be supplied.
134 Enumeration. A pointer to a ber_int_t should be supplied.
137 Integer. A pointer to a ber_int_t should be supplied.
140 Bitstring. A char ** should be supplied which will point to the
141 dynamically allocated
142 bits, followed by a ber_len_t *, which will point to the length
143 (in bits) of the bitstring returned.
146 Null. No parameter is required. The element is simply skipped if
150 Sequence of octet strings. A char *** should be supplied, which upon
151 return points to a dynamically allocated null-terminated array of char *'s
152 containing the octet strings. NULL is returned if the sequence is empty.
153 The caller should free the returned array and octet strings using
157 Sequence of octet strings with lengths.
158 A struct berval *** should be supplied, which upon
159 return points to a dynamically allocated null-terminated array of
161 containing the octet strings and their lengths.
162 NULL is returned if the sequence is empty.
163 The caller should free the returned structures using
167 Sequence of octet strings with lengths.
168 A BerVarray * should be supplied, which upon
169 return points to a dynamically allocated array of
171 containing the octet strings and their lengths. The array is terminated
172 by a struct berval with a NULL bv_val string pointer.
173 NULL is returned if the sequence is empty.
174 The caller should free the returned structures using
175 .BR ber_bvarray_free ().
178 Sequence of octet strings with lengths. This is a generalized form
179 of the previous three formats.
180 A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
181 and a ber_len_t (off).
182 Upon return (ptr) will point to a dynamically allocated array
183 whose elements are all of size (*len). A struct berval will be filled
184 starting at offset (off) in each element. The strings in each struct
185 berval reside in memory assigned to the BerElement and must not be
186 freed by the caller. The array is terminated by a struct berval
187 with a NULL bv_val string pointer. NULL is returned if the sequence
188 is empty. The number of elements in the array is also stored
189 in (*len) on return. The caller should free the returned array using
193 Length of the next element. A pointer to a ber_len_t should be supplied.
196 Tag of the next element. A pointer to a ber_tag_t should be supplied.
199 Skip element and return its tag. A pointer to a ber_tag_t should be supplied.
202 Skip element. The next element is skipped.
205 Begin sequence. No parameter is required. The initial sequence tag
206 and length are skipped.
209 End sequence. No parameter is required and no action is taken.
212 Begin set. No parameter is required. The initial set tag
213 and length are skipped.
216 End set. No parameter is required and no action is taken.
221 routine tries to interpret the next element as an integer,
222 returning the result in \fInum\fP. The tag of whatever it finds is returned
223 on success, LBER_ERROR (\-1) on failure.
226 .BR ber_get_stringb ()
227 routine is used to read an octet string into a
228 preallocated buffer. The \fIlen\fP parameter should be initialized to
229 the size of the buffer, and will contain the length of the octet string
230 read upon return. The buffer should be big enough to take the octet
231 string value plus a terminating NULL byte.
234 .BR ber_get_stringa ()
235 routine is used to dynamically allocate space into
236 which an octet string is read.
237 The caller should free the returned string using
241 .BR ber_get_stringal ()
242 routine is used to dynamically allocate space
243 into which an octet string and its length are read. It takes a
244 struct berval **, and returns the result in this parameter.
245 The caller should free the returned structure using
249 .BR ber_get_stringbv ()
250 routine is used to read an octet string and its length into the
251 provided struct berval *. If the \fIalloc\fP parameter is zero, the string
252 will reside in memory assigned to the BerElement, and must not be freed
253 by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
254 copied into dynamically allocated space which should be returned using
259 routine is used to read a NULL element. It returns
260 the tag of the element it skips over.
263 .BR ber_get_boolean ()
264 routine is used to read a boolean value. It is called the same way that
270 routine is used to read a enumeration value. It is called the same way that
275 .BR ber_get_bitstringa ()
276 routine is used to read a bitstring value. It
277 takes a char ** which will hold the dynamically allocated bits, followed by an
278 ber_len_t *, which will point to the length (in bits) of the bitstring returned.
279 The caller should free the returned string using
283 .BR ber_first_element ()
284 routine is used to return the tag and length
285 of the first element in a set or sequence. It also returns in \fIcookie\fP
286 a magic cookie parameter that should be passed to subsequent calls to
287 ber_next_element(), which returns similar information.
289 Assume the variable \fIber\fP contains a lightweight BER encoding of
290 the following ASN.1 object:
293 AlmostASearchRequest := SEQUENCE {
294 baseObject DistinguishedName,
300 derefAliases ENUMERATED {
301 neverDerefaliases (0),
302 derefInSearching (1),
303 derefFindingBaseObj (2),
304 alwaysDerefAliases (3)
306 sizelimit INTEGER (0 .. 65535),
307 timelimit INTEGER (0 .. 65535),
309 attributes SEQUENCE OF AttributeType
313 The element can be decoded using
318 ber_int_t scope, deref, size, time, attrsonly;
322 tag = ber_scanf( ber, "{aeeiib{v}}",
324 &size, &time, &attrsonly, &attrs );
326 if( tag == LBER_ERROR ) {
333 ber_memvfree( attrs );
336 If an error occurs during decoding, generally these routines return
341 The return values for all of these functions are declared in the
343 header file. Some routines may dynamically allocate memory
344 which must be freed by the caller using supplied deallocation routines.
352 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
354 is derived from University of Michigan LDAP 3.3 Release.