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

   1 .TH LBER_DECODE 3 "12 May 2000" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   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
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <lber.h>
  11 .ft
  12 .fi
  13 .LP
  14 .nf
  15 .ft B
  16 ber_tag_t ber_get_next(
  17         Sockbuf *sb,
  18         ber_len_t \(**len,
  19         BerElement \(**ber);
  20 .ft
  21 .fi
  22 .LP
  23 .nf
  24 .ft B
  25 ber_tag_t ber_skip_tag(
  26         BerElement \(**ber,
  27         ber_len_t long \(**len);
  28 .ft
  29 .fi
  30 .LP
  31 .nf
  32 .ft B
  33 ber_tag_t ber_peek_tag(
  34         BerElement \(**ber,
  35         ber_len_t \(**len);
  36 .ft
  37 .fi
  38 .LP
  39 .nf
  40 .ft B
  41 ber_tag_t ber_scanf(
  42         BerElement \(**ber,
  43         const char \(**fmt, ...);
  44 .ft
  45 .fi
  46 .LP
  47 .nf
  48 .ft B
  49 ber_tag_t ber_get_int(ber, num)
  50         BerElement \(**ber,
  51         ber_int_t \(**num);
  52 .ft
  53 .fi
  54 .LP
  55 .nf
  56 .ft B
  57 ber_tag_t ber_get_stringb(
  58         BerElement \(**ber,
  59         char \(**buf,
  60         ber_len_t \(**len);
  61 .ft
  62 .fi
  63 .LP
  64 .nf
  65 .ft B
  66 ber_tag_t ber_get_stringa(
  67         BerElement \(**ber,
  68         char \(***buf);
  69 .ft
  70 .fi
  71 .LP
  72 .nf
  73 .ft B
  74 ber_tag_t ber_get_stringal(
  75         BerElement \(**ber,
  76         struct berval \(***bv);
  77 .ft
  78 .fi
  79 .LP
  80 .nf
  81 .ft B
  82 ber_tag_t ber_get_null(
  83         BerElement \(**ber );
  84 .ft
  85 .fi
  86 .LP
  87 .nf
  88 .ft B
  89 ber_tag_t ber_get_boolean(
  90         BerElement \(**ber,
  91         ber_int_t \(**bool);
  92 .ft
  93 .fi
  94 .LP
  95 .nf
  96 .ft B
  97 ber_tag_t ber_get_bitstringa(
  98         BerElement \(**ber,
  99         char \(***buf,
 100         ber_len_t \(**blen);
 101 .ft
 102 .fi
 103 .LP
 104 .nf
 105 .ft B
 106 ber_tag_t ber_first_element(
 107         BerElement \(**ber,
 108         ber_len_t \(**len,
 109         char \(***cookie);
 110 .ft
 111 .fi
 112 .LP
 113 .nf
 114 .ft B
 115 ber_tag_t ber_next_element(
 116         BerElement \(**ber,
 117         ber_len_t \(**len,
 118         const char \(**cookie);
 119 .SH DESCRIPTION
 120 .LP
 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.
 134 .LP
 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.
 142 .LP
 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
 152 the element.
 153 .LP
 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
 161 characters.
 162 .RS
 163 .LP
 164 .TP 3
 165 .SM a
 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();
 170 .TP
 171 .SM s
 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.
 176 .TP
 177 .SM O
 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
 180 and its length.
 181 The caller should free the returned structure using ber_bvfree();
 182 .TP
 183 .SM b
 184 Boolean.  A pointer to a ber_int_t should be supplied.
 185 .TP
 186 .SM i
 187 Integer.  A pointer to a ber_int_t should be supplied.
 188 .TP
 189 .SM B
 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.
 194 .TP
 195 .SM n
 196 Null.  No parameter is required.  The element is simply skipped if
 197 it is recognized.
 198 .TP
 199 .SM v
 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.
 203 .TP
 204 .SM V
 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
 208 struct berval *'s
 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();
 212 .TP
 213 .SM x
 214 Skip element.  The next element is skipped.
 215 .TP
 216 .SM {
 217 Begin sequence.  No parameter is required.  The initial sequence tag
 218 and length are skipped.
 219 .TP
 220 .SM }
 221 End sequence.  No parameter is required and no action is taken.
 222 .TP
 223 .SM [
 224 Begin set.  No parameter is required.  The initial set tag
 225 and length are skipped.
 226 .TP
 227 .SM ]
 228 End set.  No parameter is required and no action is taken.
 229 .RE
 230 .LP
 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.
 234 .LP
 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.
 240 .LP
 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();
 244 .LP
 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();
 249 .LP
 250 The ber_get_null() routine is used to read a NULL element.  It returns
 251 the tag of the element it skips over.
 252 .LP
 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.
 255 .LP
 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
 259 bitstring returned.
 260 The caller should free the returned string using ber_memfree();
 261 .LP
 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.
 266 .SH EXAMPLES
 267 Assume the variable \fIber\fP contains a lightweight BER encoding of
 268 the following ASN.1 object:
 269 .LP
 270 .nf
 271       AlmostASearchRequest := SEQUENCE {
 272           baseObject      DistinguishedName,
 273           scope           ENUMERATED {
 274               baseObject    (0),
 275               singleLevel   (1),
 276               wholeSubtree  (2)
 277           },
 278           derefAliases    ENUMERATED {
 279               neverDerefaliases   (0),
 280               derefInSearching    (1),
 281               derefFindingBaseObj (2),
 282               alwaysDerefAliases  (3)
 283           },
 284           sizelimit       INTEGER (0 .. 65535),
 285           timelimit       INTEGER (0 .. 65535),
 286           attrsOnly       BOOLEAN,
 287           attributes      SEQUENCE OF AttributeType
 288       }
 289 .fi
 290 .LP
 291 The element can be decoded using ber_scanf() as follows.
 292 .LP
 293 .nf
 294       ber_int_t    scope, ali, size, time, attrsonly;
 295       char   *dn, **attrs;
 296       ber_tag_t tag;
 297
 298       tag = ber_scanf( ber, "{aiiiib{v}}",
 299           &dn, &scope, &ali,
 300           &size, &time, &attrsonly, &attrs );
 301
 302       if( tag == LBER_ERROR ) {
 303               /* error */
 304       } else {
 305               /* success */
 306       }
 307 .fi
 308 .SH ERRORS
 309 If an error occurs during decoding, generally these routines return
 310 LBER_ERROR (\-1).
 311 .LP
 312 .SH NOTES
 313 .LP
 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.
 318 .SH SEE ALSO
 319 .BR lber-encode (3)
 320 .BR lber-types (3)
 321 .BR ldap-parse (3)
 322 .BR ldap-sync (3)
 323 .BR ldap-async (3)
 324 .LP
 325 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
 326 Protocol", OSI-DS-26, April 1992.
 327 .LP
 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.
 332 .SH AUTHOR
 333 Tim Howes, University of Michigan
 334 .SH ACKNOWLEDGEMENTS
 335 .B      OpenLDAP
 336 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 337 .B      OpenLDAP
 338 is derived from University of Michigan LDAP 3.3 Release.