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

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