git.sur5r.net Git - openldap/blob - doc/man/man3/lber-decode.3

   1 .TH LBER_DECODE 3 "25 January 2002" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   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
  11 .SH SYNOPSIS
  12 .B #include <lber.h>
  13 .LP
  14 .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
  15 .LP
  16 .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
  17 .LP
  18 .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
  19 .LP
  20 .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
  21 .LP
  22 .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
  23 .LP
  24 .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
  25 .LP
  26 .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
  27 .LP
  28 .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
  29 .LP
  30 .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
  31 .LP
  32 .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
  33 .LP
  34 .BI "ber_tag_t ber_get_null(BerElement *" ber ");"
  35 .LP
  36 .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
  37 .LP
  38 .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
  39 .LP
  40 .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
  41 .LP
  42 .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
  43 .SH DESCRIPTION
  44 .LP
  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
  52 .BR lber-encode (3)
  53 for details on the corresponding encoding routines.
  54 Consult
  55 .BR lber-types (3)
  56 for information about types, allocators, and deallocators.
  57 .LP
  58 Normally, the only routines that need to be called by an application
  59 are
  60 .BR ber_get_next ()
  61 to get the next BER element and
  62 .BR ber_scanf ()
  63 to do the actual decoding.  In some cases,
  64 .BR ber_peek_tag ()
  65 may also need to be called in normal usage.  The other routines are
  66 provided for those applications that need more control than
  67 .BR ber_scanf ()
  68 provides.  In
  69 general, these routines return the tag of the element decoded, or
  70 LBER_ERROR if an error occurred.
  71 .LP
  72 The
  73 .BR ber_get_next ()
  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
  78 .BR ber_scanf ()
  79 et al to decode the element. See
  80 .BR lber-sockbuf (3)
  81 for details of the Sockbuf implementation of the \fIsb\fP parameter.
  82 .LP
  83 The
  84 .BR ber_scanf ()
  85 routine is used to decode a BER element in much the same way that
  86 .BR scanf (3)
  87 works.  It reads from \fIber\fP, a pointer to a BerElement
  88 such as returned by
  89 .BR ber_get_next (),
  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
  94 characters.
  95 .RS
  96 .LP
  97 .TP 3
  98 .B a
  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
 102 string using
 103 .BR ber_memfree ().
 104 .TP
 105 .B s
 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.
 110 .TP
 111 .B O
 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
 116 .BR ber_bvfree ().
 117 .TP
 118 .B o
 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
 122 string using
 123 .BR ber_memfree ().
 124 .TP
 125 .B m
 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.
 129 .TP
 130 .B b
 131 Boolean.  A pointer to a ber_int_t should be supplied.
 132 .TP
 133 .B e
 134 Enumeration.  A pointer to a ber_int_t should be supplied.
 135 .TP
 136 .B i
 137 Integer.  A pointer to a ber_int_t should be supplied.
 138 .TP
 139 .B B
 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.
 144 .TP
 145 .B n
 146 Null.  No parameter is required.  The element is simply skipped if
 147 it is recognized.
 148 .TP
 149 .B v
 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
 154 .BR ber_memvfree ().
 155 .TP
 156 .B V
 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
 160 struct berval *'s
 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
 164 .BR ber_bvecfree ().
 165 .TP
 166 .B W
 167 Sequence of octet strings with lengths.
 168 A BerVarray * should be supplied, which upon
 169 return points to a dynamically allocated array of
 170 struct berval's
 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 ().
 176 .TP
 177 .B M
 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
 190 .BR ber_memfree ().
 191 .TP
 192 .B l
 193 Length of the next element.  A pointer to a ber_len_t should be supplied.
 194 .TP
 195 .B t
 196 Tag of the next element.  A pointer to a ber_tag_t should be supplied.
 197 .TP
 198 .B T
 199 Skip element and return its tag.  A pointer to a ber_tag_t should be supplied.
 200 .TP
 201 .B x
 202 Skip element.  The next element is skipped.
 203 .TP
 204 .B {
 205 Begin sequence.  No parameter is required.  The initial sequence tag
 206 and length are skipped.
 207 .TP
 208 .B }
 209 End sequence.  No parameter is required and no action is taken.
 210 .TP
 211 .B [
 212 Begin set.  No parameter is required.  The initial set tag
 213 and length are skipped.
 214 .TP
 215 .B ]
 216 End set.  No parameter is required and no action is taken.
 217 .RE
 218 .LP
 219 The
 220 .BR ber_get_int ()
 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.
 224 .LP
 225 The
 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.
 232 .LP
 233 The
 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
 238 .BR ber_memfree().
 239 .LP
 240 The
 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
 246 .BR ber_bvfree().
 247 .LP
 248 The
 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
 255 .BR ber_memfree ().
 256 .LP
 257 The
 258 .BR ber_get_null ()
 259 routine is used to read a NULL element.  It returns
 260 the tag of the element it skips over.
 261 .LP
 262 The
 263 .BR ber_get_boolean ()
 264 routine is used to read a boolean value.  It is called the same way that
 265 .BR ber_get_int ()
 266 is called.
 267 .LP
 268 The
 269 .BR ber_get_enum ()
 270 routine is used to read a enumeration value.  It is called the same way that
 271 .BR ber_get_int ()
 272 is called.
 273 .LP
 274 The
 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
 280 .BR ber_memfree ().
 281 .LP
 282 The
 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.
 288 .SH EXAMPLES
 289 Assume the variable \fIber\fP contains a lightweight BER encoding of
 290 the following ASN.1 object:
 291 .LP
 292 .nf
 293       AlmostASearchRequest := SEQUENCE {
 294           baseObject      DistinguishedName,
 295           scope           ENUMERATED {
 296               baseObject    (0),
 297               singleLevel   (1),
 298               wholeSubtree  (2)
 299           },
 300           derefAliases    ENUMERATED {
 301               neverDerefaliases   (0),
 302               derefInSearching    (1),
 303               derefFindingBaseObj (2),
 304               alwaysDerefAliases  (3)
 305           },
 306           sizelimit       INTEGER (0 .. 65535),
 307           timelimit       INTEGER (0 .. 65535),
 308           attrsOnly       BOOLEAN,
 309           attributes      SEQUENCE OF AttributeType
 310       }
 311 .fi
 312 .LP
 313 The element can be decoded using
 314 .BR ber_scanf ()
 315 as follows.
 316 .LP
 317 .nf
 318       ber_int_t    scope, deref, size, time, attrsonly;
 319       char   *dn, **attrs;
 320       ber_tag_t tag;
 321
 322       tag = ber_scanf( ber, "{aeeiib{v}}",
 323           &dn, &scope, &deref,
 324           &size, &time, &attrsonly, &attrs );
 325
 326       if( tag == LBER_ERROR ) {
 327               /* error */
 328       } else {
 329               /* success */
 330       }
 331
 332       ber_memfree( dn );
 333       ber_memvfree( attrs );
 334 .fi
 335 .SH ERRORS
 336 If an error occurs during decoding, generally these routines return
 337 LBER_ERROR (\-1).
 338 .LP
 339 .SH NOTES
 340 .LP
 341 The return values for all of these functions are declared in the
 342 .B <lber.h>
 343 header file.  Some routines may dynamically allocate memory
 344 which must be freed by the caller using supplied deallocation routines.
 345 .SH SEE ALSO
 346 .BR lber-encode (3)
 347 .BR lber-memory (3)
 348 .BR lber-sockbuf (3)
 349 .BR lber-types (3)
 350 .SH ACKNOWLEDGEMENTS
 351 .B      OpenLDAP
 352 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 353 .B      OpenLDAP
 354 is derived from University of Michigan LDAP 3.3 Release.