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

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