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-2012 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, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding
   7 .SH LIBRARY
   8 OpenLDAP LBER (liblber, \-llber)
   9 .SH SYNOPSIS
  10 .B #include <lber.h>
  11 .LP
  12 .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
  13 .LP
  14 .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
  15 .LP
  16 .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
  17 .LP
  18 .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
  19 .LP
  20 .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
  21 .LP
  22 .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
  23 .LP
  24 .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
  25 .LP
  26 .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
  27 .LP
  28 .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
  29 .LP
  30 .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
  31 .LP
  32 .BI "ber_tag_t ber_get_null(BerElement *" ber ");"
  33 .LP
  34 .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
  35 .LP
  36 .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
  37 .LP
  38 .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
  39 .LP
  40 .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
  41 .SH DESCRIPTION
  42 .LP
  43 These routines provide a subroutine interface to a simplified
  44 implementation of the Basic Encoding Rules of ASN.1.  The version
  45 of BER these routines support is the one defined for the LDAP
  46 protocol.  The encoding rules are the same as BER, except that
  47 only definite form lengths are used, and bitstrings and octet strings
  48 are always encoded in primitive form.  This man page
  49 describes the decoding routines in the lber library.  See
  50 .BR lber-encode (3)
  51 for details on the corresponding encoding routines.
  52 Consult
  53 .BR lber-types (3)
  54 for information about types, allocators, and deallocators.
  55 .LP
  56 Normally, the only routines that need to be called by an application
  57 are
  58 .BR ber_get_next ()
  59 to get the next BER element and
  60 .BR ber_scanf ()
  61 to do the actual decoding.  In some cases,
  62 .BR ber_peek_tag ()
  63 may also need to be called in normal usage.  The other routines are
  64 provided for those applications that need more control than
  65 .BR ber_scanf ()
  66 provides.  In
  67 general, these routines return the tag of the element decoded, or
  68 LBER_ERROR if an error occurred.
  69 .LP
  70 The
  71 .BR ber_get_next ()
  72 routine is used to read the next BER element from the given Sockbuf,
  73 \fIsb\fP.  It strips off and returns the leading tag, strips off and
  74 returns the length of the entire element in \fIlen\fP, and sets up
  75 \fIber\fP for subsequent calls to
  76 .BR ber_scanf ()
  77 et al to decode the element. See
  78 .BR lber-sockbuf (3)
  79 for details of the Sockbuf implementation of the \fIsb\fP parameter.
  80 .LP
  81 The
  82 .BR ber_scanf ()
  83 routine is used to decode a BER element in much the same way that
  84 .BR scanf (3)
  85 works.  It reads from \fIber\fP, a pointer to a BerElement
  86 such as returned by
  87 .BR ber_get_next (),
  88 interprets the bytes according to the format string \fIfmt\fP, and stores the
  89 results in its additional arguments.  The format string contains
  90 conversion specifications which are used to direct the interpretation
  91 of the BER element.  The format string can contain the following
  92 characters.
  93 .RS
  94 .LP
  95 .TP 3
  96 .B a
  97 Octet string.  A char ** should be supplied.  Memory is allocated,
  98 filled with the contents of the octet string, null-terminated, and
  99 returned in the parameter.  The caller should free the returned
 100 string using
 101 .BR ber_memfree ().
 102 .TP
 103 .B A
 104 Octet string.  A variant of "\fBa\fP".  A char ** should be supplied.
 105 Memory is allocated, filled with the contents of the octet string,
 106 null-terminated, and returned in the parameter, unless a zero-length
 107 string would result; in that case, the arg is set to NULL.
 108 The caller should free the returned string using
 109 .BR ber_memfree ().
 110 .TP
 111 .B s
 112 Octet string.  A char * buffer should be supplied, followed by a pointer to a
 113 ber_len_t initialized to the size of the buffer.  Upon return, the
 114 null-terminated octet string is put into the buffer, and the
 115 ber_len_t is set to the actual size of the octet string.
 116 .TP
 117 .B O
 118 Octet string.  A struct ber_val ** should be supplied, which upon
 119 return points to a dynamically allocated struct berval
 120 containing the octet string and its length.
 121 The caller should free the returned structure using
 122 .BR ber_bvfree ().
 123 .TP
 124 .B o
 125 Octet string.  A struct ber_val * should be supplied, which upon
 126 return contains the dynamically allocated
 127 octet string and its length.  The caller should free the returned octet
 128 string using
 129 .BR ber_memfree ().
 130 .TP
 131 .B m
 132 Octet string.  A struct ber_val * should be supplied, which upon return
 133 contains the octet string and its length.  The string resides in memory
 134 assigned to the BerElement, and must not be freed by the caller.
 135 .TP
 136 .B b
 137 Boolean.  A pointer to a ber_int_t should be supplied.
 138 .TP
 139 .B e
 140 Enumeration.  A pointer to a ber_int_t should be supplied.
 141 .TP
 142 .B i
 143 Integer.  A pointer to a ber_int_t should be supplied.
 144 .TP
 145 .B B
 146 Bitstring.  A char ** should be supplied which will point to the
 147 dynamically allocated
 148 bits, followed by a ber_len_t *, which will point to the length
 149 (in bits) of the bitstring returned.
 150 .TP
 151 .B n
 152 Null.  No parameter is required.  The element is simply skipped if
 153 it is recognized.
 154 .TP
 155 .B v
 156 Sequence of octet strings.  A char *** should be supplied, which upon
 157 return points to a dynamically allocated null-terminated array of char *'s
 158 containing the octet strings.  NULL is returned if the sequence is empty.
 159 The caller should free the returned array and octet strings using
 160 .BR ber_memvfree ().
 161 .TP
 162 .B V
 163 Sequence of octet strings with lengths.
 164 A struct berval *** should be supplied, which upon
 165 return points to a dynamically allocated null-terminated array of
 166 struct berval *'s
 167 containing the octet strings and their lengths.
 168 NULL is returned if the sequence is empty.
 169 The caller should free the returned structures using
 170 .BR ber_bvecfree ().
 171 .TP
 172 .B W
 173 Sequence of octet strings with lengths.
 174 A BerVarray * should be supplied, which upon
 175 return points to a dynamically allocated array of
 176 struct berval's
 177 containing the octet strings and their lengths. The array is terminated
 178 by a struct berval with a NULL bv_val string pointer.
 179 NULL is returned if the sequence is empty.
 180 The caller should free the returned structures using
 181 .BR ber_bvarray_free ().
 182 .TP
 183 .B M
 184 Sequence of octet strings with lengths.  This is a generalized form
 185 of the previous three formats.
 186 A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
 187 and a ber_len_t (off).
 188 Upon return (ptr) will point to a dynamically allocated array
 189 whose elements are all of size (*len).  A struct berval will be filled
 190 starting at offset (off) in each element.  The strings in each struct
 191 berval reside in memory assigned to the BerElement and must not be
 192 freed by the caller.  The array is terminated by a struct berval
 193 with a NULL bv_val string pointer.  NULL is returned if the sequence
 194 is empty.  The number of elements in the array is also stored
 195 in (*len) on return.  The caller should free the returned array using
 196 .BR ber_memfree ().
 197 .TP
 198 .B l
 199 Length of the next element.  A pointer to a ber_len_t should be supplied.
 200 .TP
 201 .B t
 202 Tag of the next element.  A pointer to a ber_tag_t should be supplied.
 203 .TP
 204 .B T
 205 Skip element and return its tag.  A pointer to a ber_tag_t should be supplied.
 206 .TP
 207 .B x
 208 Skip element.  The next element is skipped.
 209 .TP
 210 .B {
 211 Begin sequence.  No parameter is required.  The initial sequence tag
 212 and length are skipped.
 213 .TP
 214 .B }
 215 End sequence.  No parameter is required and no action is taken.
 216 .TP
 217 .B [
 218 Begin set.  No parameter is required.  The initial set tag
 219 and length are skipped.
 220 .TP
 221 .B ]
 222 End set.  No parameter is required and no action is taken.
 223 .RE
 224 .LP
 225 The
 226 .BR ber_get_int ()
 227 routine tries to interpret the next element as an integer,
 228 returning the result in \fInum\fP.  The tag of whatever it finds is returned
 229 on success, LBER_ERROR (\-1) on failure.
 230 .LP
 231 The
 232 .BR ber_get_stringb ()
 233 routine is used to read an octet string into a
 234 preallocated buffer.  The \fIlen\fP parameter should be initialized to
 235 the size of the buffer, and will contain the length of the octet string
 236 read upon return.  The buffer should be big enough to take the octet
 237 string value plus a terminating NULL byte.
 238 .LP
 239 The
 240 .BR ber_get_stringa ()
 241 routine is used to dynamically allocate space into
 242 which an octet string is read.
 243 The caller should free the returned string using
 244 .BR ber_memfree().
 245 .LP
 246 The
 247 .BR ber_get_stringal ()
 248 routine is used to dynamically allocate space
 249 into which an octet string and its length are read.  It takes a
 250 struct berval **, and returns the result in this parameter.
 251 The caller should free the returned structure using
 252 .BR ber_bvfree().
 253 .LP
 254 The
 255 .BR ber_get_stringbv ()
 256 routine is used to read an octet string and its length into the
 257 provided struct berval *. If the \fIalloc\fP parameter is zero, the string
 258 will reside in memory assigned to the BerElement, and must not be freed
 259 by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
 260 copied into dynamically allocated space which should be returned using
 261 .BR ber_memfree ().
 262 .LP
 263 The
 264 .BR ber_get_null ()
 265 routine is used to read a NULL element.  It returns
 266 the tag of the element it skips over.
 267 .LP
 268 The
 269 .BR ber_get_boolean ()
 270 routine is used to read a boolean value.  It is called the same way that
 271 .BR ber_get_int ()
 272 is called.
 273 .LP
 274 The
 275 .BR ber_get_enum ()
 276 routine is used to read a enumeration value.  It is called the same way that
 277 .BR ber_get_int ()
 278 is called.
 279 .LP
 280 The
 281 .BR ber_get_bitstringa ()
 282 routine is used to read a bitstring value.  It
 283 takes a char ** which will hold the dynamically allocated bits, followed by an
 284 ber_len_t *, which will point to the length (in bits) of the bitstring returned.
 285 The caller should free the returned string using
 286 .BR ber_memfree ().
 287 .LP
 288 The
 289 .BR ber_first_element ()
 290 routine is used to return the tag and length
 291 of the first element in a set or sequence.  It also returns in \fIcookie\fP
 292 a magic cookie parameter that should be passed to subsequent calls to
 293 ber_next_element(), which returns similar information.
 294 .SH EXAMPLES
 295 Assume the variable \fIber\fP contains a lightweight BER encoding of
 296 the following ASN.1 object:
 297 .LP
 298 .nf
 299       AlmostASearchRequest := SEQUENCE {
 300           baseObject      DistinguishedName,
 301           scope           ENUMERATED {
 302               baseObject    (0),
 303               singleLevel   (1),
 304               wholeSubtree  (2)
 305           },
 306           derefAliases    ENUMERATED {
 307               neverDerefaliases   (0),
 308               derefInSearching    (1),
 309               derefFindingBaseObj (2),
 310               alwaysDerefAliases  (3)
 311           },
 312           sizelimit       INTEGER (0 .. 65535),
 313           timelimit       INTEGER (0 .. 65535),
 314           attrsOnly       BOOLEAN,
 315           attributes      SEQUENCE OF AttributeType
 316       }
 317 .fi
 318 .LP
 319 The element can be decoded using
 320 .BR ber_scanf ()
 321 as follows.
 322 .LP
 323 .nf
 324       ber_int_t    scope, deref, size, time, attrsonly;
 325       char   *dn, **attrs;
 326       ber_tag_t tag;
 327
 328       tag = ber_scanf( ber, "{aeeiib{v}}",
 329           &dn, &scope, &deref,
 330           &size, &time, &attrsonly, &attrs );
 331
 332       if( tag == LBER_ERROR ) {
 333               /* error */
 334       } else {
 335               /* success */
 336       }
 337
 338       ber_memfree( dn );
 339       ber_memvfree( attrs );
 340 .fi
 341 .SH ERRORS
 342 If an error occurs during decoding, generally these routines return
 343 LBER_ERROR ((ber_tag_t)\-1).
 344 .LP
 345 .SH NOTES
 346 .LP
 347 The return values for all of these functions are declared in the
 348 .B <lber.h>
 349 header file.  Some routines may dynamically allocate memory
 350 which must be freed by the caller using supplied deallocation routines.
 351 .SH SEE ALSO
 352 .BR lber-encode (3),
 353 .BR lber-memory (3),
 354 .BR lber-sockbuf (3),
 355 .BR lber-types (3)
 356 .SH ACKNOWLEDGEMENTS
 357 .so ../Project