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

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