1 .TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2005 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
12 OpenLDAP LBER (liblber, -llber)
16 .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
18 .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
20 .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
22 .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
24 .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
26 .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
28 .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
30 .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
32 .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
34 .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
36 .BI "ber_tag_t ber_get_null(BerElement *" ber ");"
38 .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
40 .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
42 .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
44 .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
47 These routines provide a subroutine interface to a simplified
48 implementation of the Basic Encoding Rules of ASN.1. The version
49 of BER these routines support is the one defined for the LDAP
50 protocol. The encoding rules are the same as BER, except that
51 only definite form lengths are used, and bitstrings and octet strings
52 are always encoded in primitive form. This man page
53 describes the decoding routines in the lber library. See
55 for details on the corresponding encoding routines.
58 for information about types, allocators, and deallocators.
60 Normally, the only routines that need to be called by an application
63 to get the next BER element and
65 to do the actual decoding. In some cases,
67 may also need to be called in normal usage. The other routines are
68 provided for those applications that need more control than
71 general, these routines return the tag of the element decoded, or
72 LBER_ERROR if an error occurred.
76 routine is used to read the next BER element from the given Sockbuf,
77 \fIsb\fP. It strips off and returns the leading tag, strips off and
78 returns the length of the entire element in \fIlen\fP, and sets up
79 \fIber\fP for subsequent calls to
81 et al to decode the element. See
83 for details of the Sockbuf implementation of the \fIsb\fP parameter.
87 routine is used to decode a BER element in much the same way that
89 works. It reads from \fIber\fP, a pointer to a BerElement
92 interprets the bytes according to the format string \fIfmt\fP, and stores the
93 results in its additional arguments. The format string contains
94 conversion specifications which are used to direct the interpretation
95 of the BER element. The format string can contain the following
101 Octet string. A char ** should be supplied. Memory is allocated,
102 filled with the contents of the octet string, null-terminated, and
103 returned in the parameter. The caller should free the returned
108 Octet string. A char * buffer should be supplied, followed by a pointer to a
109 ber_len_t initialized to the size of the buffer. Upon return, the
110 null-terminated octet string is put into the buffer, and the
111 ber_len_t is set to the actual size of the octet string.
114 Octet string. A struct ber_val ** should be supplied, which upon
115 return points to a dynamically allocated struct berval
116 containing the octet string and its length.
117 The caller should free the returned structure using
121 Octet string. A struct ber_val * should be supplied, which upon
122 return contains the dynamically allocated
123 octet string and its length. The caller should free the returned octet
128 Octet string. A struct ber_val * should be supplied, which upon return
129 contains the octet string and its length. The string resides in memory
130 assigned to the BerElement, and must not be freed by the caller.
133 Boolean. A pointer to a ber_int_t should be supplied.
136 Enumeration. A pointer to a ber_int_t should be supplied.
139 Integer. A pointer to a ber_int_t should be supplied.
142 Bitstring. A char ** should be supplied which will point to the
143 dynamically allocated
144 bits, followed by a ber_len_t *, which will point to the length
145 (in bits) of the bitstring returned.
148 Null. No parameter is required. The element is simply skipped if
152 Sequence of octet strings. A char *** should be supplied, which upon
153 return points to a dynamically allocated null-terminated array of char *'s
154 containing the octet strings. NULL is returned if the sequence is empty.
155 The caller should free the returned array and octet strings using
159 Sequence of octet strings with lengths.
160 A struct berval *** should be supplied, which upon
161 return points to a dynamically allocated null-terminated array of
163 containing the octet strings and their lengths.
164 NULL is returned if the sequence is empty.
165 The caller should free the returned structures using
169 Sequence of octet strings with lengths.
170 A BerVarray * should be supplied, which upon
171 return points to a dynamically allocated array of
173 containing the octet strings and their lengths. The array is terminated
174 by a struct berval with a NULL bv_val string pointer.
175 NULL is returned if the sequence is empty.
176 The caller should free the returned structures using
177 .BR ber_bvarray_free ().
180 Sequence of octet strings with lengths. This is a generalized form
181 of the previous three formats.
182 A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
183 and a ber_len_t (off).
184 Upon return (ptr) will point to a dynamically allocated array
185 whose elements are all of size (*len). A struct berval will be filled
186 starting at offset (off) in each element. The strings in each struct
187 berval reside in memory assigned to the BerElement and must not be
188 freed by the caller. The array is terminated by a struct berval
189 with a NULL bv_val string pointer. NULL is returned if the sequence
190 is empty. The number of elements in the array is also stored
191 in (*len) on return. The caller should free the returned array using
195 Length of the next element. A pointer to a ber_len_t should be supplied.
198 Tag of the next element. A pointer to a ber_tag_t should be supplied.
201 Skip element and return its tag. A pointer to a ber_tag_t should be supplied.
204 Skip element. The next element is skipped.
207 Begin sequence. No parameter is required. The initial sequence tag
208 and length are skipped.
211 End sequence. No parameter is required and no action is taken.
214 Begin set. No parameter is required. The initial set tag
215 and length are skipped.
218 End set. No parameter is required and no action is taken.
223 routine tries to interpret the next element as an integer,
224 returning the result in \fInum\fP. The tag of whatever it finds is returned
225 on success, LBER_ERROR (\-1) on failure.
228 .BR ber_get_stringb ()
229 routine is used to read an octet string into a
230 preallocated buffer. The \fIlen\fP parameter should be initialized to
231 the size of the buffer, and will contain the length of the octet string
232 read upon return. The buffer should be big enough to take the octet
233 string value plus a terminating NULL byte.
236 .BR ber_get_stringa ()
237 routine is used to dynamically allocate space into
238 which an octet string is read.
239 The caller should free the returned string using
243 .BR ber_get_stringal ()
244 routine is used to dynamically allocate space
245 into which an octet string and its length are read. It takes a
246 struct berval **, and returns the result in this parameter.
247 The caller should free the returned structure using
251 .BR ber_get_stringbv ()
252 routine is used to read an octet string and its length into the
253 provided struct berval *. If the \fIalloc\fP parameter is zero, the string
254 will reside in memory assigned to the BerElement, and must not be freed
255 by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
256 copied into dynamically allocated space which should be returned using
261 routine is used to read a NULL element. It returns
262 the tag of the element it skips over.
265 .BR ber_get_boolean ()
266 routine is used to read a boolean value. It is called the same way that
272 routine is used to read a enumeration value. It is called the same way that
277 .BR ber_get_bitstringa ()
278 routine is used to read a bitstring value. It
279 takes a char ** which will hold the dynamically allocated bits, followed by an
280 ber_len_t *, which will point to the length (in bits) of the bitstring returned.
281 The caller should free the returned string using
285 .BR ber_first_element ()
286 routine is used to return the tag and length
287 of the first element in a set or sequence. It also returns in \fIcookie\fP
288 a magic cookie parameter that should be passed to subsequent calls to
289 ber_next_element(), which returns similar information.
291 Assume the variable \fIber\fP contains a lightweight BER encoding of
292 the following ASN.1 object:
295 AlmostASearchRequest := SEQUENCE {
296 baseObject DistinguishedName,
302 derefAliases ENUMERATED {
303 neverDerefaliases (0),
304 derefInSearching (1),
305 derefFindingBaseObj (2),
306 alwaysDerefAliases (3)
308 sizelimit INTEGER (0 .. 65535),
309 timelimit INTEGER (0 .. 65535),
311 attributes SEQUENCE OF AttributeType
315 The element can be decoded using
320 ber_int_t scope, deref, size, time, attrsonly;
324 tag = ber_scanf( ber, "{aeeiib{v}}",
326 &size, &time, &attrsonly, &attrs );
328 if( tag == LBER_ERROR ) {
335 ber_memvfree( attrs );
338 If an error occurs during decoding, generally these routines return
339 LBER_ERROR ((ber_tag_t)\-1).
343 The return values for all of these functions are declared in the
345 header file. Some routines may dynamically allocate memory
346 which must be freed by the caller using supplied deallocation routines.
350 .BR lber-sockbuf (3),
354 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
356 is derived from University of Michigan LDAP 3.3 Release.