1 .TH LBER_DECODE 3 "12 May 2000" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ber_get_next, ber_skiptag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_stringb, ber_get_stringa, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- LBER simplified Basic Encoding Rules library routines for decoding
16 ber_tag_t ber_get_next(
25 ber_tag_t ber_skip_tag(
27 ber_len_t long \(**len);
33 ber_tag_t ber_peek_tag(
43 const char \(**fmt, ...);
49 ber_tag_t ber_get_int(ber, num)
57 ber_tag_t ber_get_stringb(
66 ber_tag_t ber_get_stringa(
74 ber_tag_t ber_get_stringal(
76 struct berval \(***bv);
82 ber_tag_t ber_get_null(
89 ber_tag_t ber_get_boolean(
97 ber_tag_t ber_get_bitstringa(
106 ber_tag_t ber_first_element(
115 ber_tag_t ber_next_element(
118 const char \(**cookie);
121 These routines provide a subroutine interface to a simplified
122 implementation of the Basic Encoding Rules of ASN.1. The version
123 of BER these routines support is the one defined for the LDAP
124 protocol. The encoding rules are the same as BER, except that
125 only definite form lengths are used, and bitstrings and octet strings
126 are always encoded in primitive form. In addition, these lightweight
127 BER routines restrict tags and class to fit in a single octet (this
128 means the actual tag must be less than 31). When a "tag" is specified
129 in the descriptions below, it refers to the tag, class, and primitive
130 or constructed bit in the first octet of the encoding. This man page
131 describes the decoding routines in the lber library. See lber-encode(3)
132 for details on the corresponding encoding routines.
133 Consult lber-types(3) for information about types, allocators, and deallocators.
135 Normally, the only routines that need be called by an application
136 are ber_get_next() to get the next BER element and ber_scanf()
137 to do the actual decoding. In some cases, ber_peek_tag() may also
138 need to be called in normal usage. The other routines are provided for those
139 applications that need more control than ber_scanf() provides. In
140 general, these routines return the tag of the element decoded, or
141 -1 if an error occurred.
143 The ber_get_next() routine is used to read the next BER element from
144 the given Sockbuf, \fIsb\fP. A Sockbuf consists of the descriptor
145 (usually socket, but a file descriptor works just as well) from which
146 to read, and a BerElement structure used
147 to maintain a buffer. On the first call, the \fIsb_ber\fP struct should
148 be zeroed. It strips off and returns the
149 leading tag byte, strips off and returns the length of the
150 entire element in \fIlen\fP,
151 and sets up \fIber\fP for subsequent calls to ber_scanf() et al to decode
154 The ber_scanf() routine is used to decode a BER element in much the
155 same way that scanf(3) works. It reads from \fIber\fP, a pointer to a
156 BerElement such as returned by ber_get_next(), interprets the
157 bytes according to the format string \fIfmt\fP, and stores the
158 results in its additional arguments. The format string contains
159 conversion specifications which are used to direct the interpretation
160 of the BER element. The format string can contain the following
166 Octet string. A char ** should be supplied. Memory is allocated,
167 filled with the contents of the octet string, null-terminated, and
168 returned in the parameter.
169 The caller should free the returned ber_val using ber_memfree();
172 Octet string. A char * buffer should be supplied, followed by a pointer
173 to a ber_len_t initialized to the size of the buffer. Upon return, the
174 null-terminated octet string is put into the buffer, and the integer is
175 set to the actual size of the octet string.
178 Octet string. A struct ber_val ** should be supplied, which upon return
179 points to a dynamically allocated struct berval containing the octet string
181 The caller should free the returned structure using ber_bvfree();
184 Boolean. A pointer to a ber_int_t should be supplied.
187 Integer. A pointer to a ber_int_t should be supplied.
190 Bitstring. A char ** should be supplied which will point to the
191 dynamically allocated
192 bits, followed by an ber_len_t *, which will point to the length
193 (in bits) of the bitstring returned.
196 Null. No parameter is required. The element is simply skipped if
200 Sequence of octet strings. A char *** should be supplied, which upon
201 return points to a dynamically allocated null-terminated array of char *'s
202 containing the octet strings. NULL is returned if the sequence is empty.
205 Sequence of octet strings with lengths.
206 A struct berval *** should be supplied, which upon
207 return points to a dynamically allocated null-terminated array of
209 containing the octet strings and their lengths.
210 NULL is returned if the sequence is empty.
211 The caller should free the returned structures using ber_bvecfree();
214 Skip element. The next element is skipped.
217 Begin sequence. No parameter is required. The initial sequence tag
218 and length are skipped.
221 End sequence. No parameter is required and no action is taken.
224 Begin set. No parameter is required. The initial set tag
225 and length are skipped.
228 End set. No parameter is required and no action is taken.
231 The ber_get_int() routine tries to interpret the next element as an integer,
232 returning the result in \fInum\fP. The tag of whatever it finds is returned
233 on success, LBER_ERROR (\-1) on failure.
235 The ber_get_stringb() routine is used to read an octet string into a
236 preallocated buffer. The \fIlen\fP parameter should be initialized to
237 the size of the buffer, and will contain the length of the octet string
238 read upon return. The buffer should be big enough to take the octet
239 string value plus a terminating NULL byte.
241 The ber_get_stringa() routine is used to dynamically allocate space into
242 which an octet string is read.
243 The caller should free the returned string using ber_memfree();
245 The ber_get_stringal() routine is used to dynamically allocate space
246 into which an octet string and its length are read. It takes a
247 struct berval **, and returns the result in this parameter.
248 The caller should free the returned structure using ber_bvfree();
250 The ber_get_null() routine is used to read a NULL element. It returns
251 the tag of the element it skips over.
253 The ber_get_boolean() routine is used to read a boolean value. It is called
254 the same way that ber_get_int() is called.
256 The ber_get_bitstringa() routine is used to read a bitstring value. It
257 takes a char ** which will hold the dynamically allocated bits, followed by an
258 unsigned long *, which will point to the length (in bits) of the
260 The caller should free the returned string using ber_memfree();
262 The ber_first_element() routine is used to return the tag and length
263 of the first element in a set or sequence. It also returns in \fIcookie\fP
264 a magic cookie parameter that should be passed to subsequent calls to
265 ber_next_element(), which returns similar information.
267 Assume the variable \fIber\fP contains a lightweight BER encoding of
268 the following ASN.1 object:
271 AlmostASearchRequest := SEQUENCE {
272 baseObject DistinguishedName,
278 derefAliases ENUMERATED {
279 neverDerefaliases (0),
280 derefInSearching (1),
281 derefFindingBaseObj (2),
282 alwaysDerefAliases (3)
284 sizelimit INTEGER (0 .. 65535),
285 timelimit INTEGER (0 .. 65535),
287 attributes SEQUENCE OF AttributeType
291 The element can be decoded using ber_scanf() as follows.
294 ber_int_t scope, ali, size, time, attrsonly;
298 tag = ber_scanf( ber, "{aiiiib{v}}",
300 &size, &time, &attrsonly, &attrs );
302 if( tag == LBER_ERROR ) {
309 If an error occurs during decoding, generally these routines return
314 The return values for all of these functions are declared in the
315 <lber.h> header file.
316 Some routines may dynamically allocate memory
317 which must be freed by the caller using supplied deallocation routines.
325 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
326 Protocol", OSI-DS-26, April 1992.
328 Information Processing - Open Systems Interconnection - Model and Notation -
329 Service Definition - Specification of Basic Encoding Rules for Abstract
330 Syntax Notation One, International Organization for Standardization,
331 International Standard 8825.
333 Tim Howes, University of Michigan
336 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
338 is derived from University of Michigan LDAP 3.3 Release.