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 malloced struct berval containing the octet string and its
 210 length.  ber_bvfree() can be called to free the malloced memory.
 211 .TP
 212 .SM b
 213 Boolean.  A pointer to an integer should be supplied.
 214 .TP
 215 .SM i
 216 Integer.  A pointer to an integer should be supplied.
 217 .TP
 218 .SM B
 219 Bitstring.  A char ** should be supplied which will point to the malloced
 220 bits, followed by an unsigned long *, which will point to the length
 221 (in bits) of the bitstring returned.
 222 .TP
 223 .SM n
 224 Null.  No parameter is required.  The element is simply skipped if
 225 it is recognized.
 226 .TP
 227 .SM v
 228 Sequence of octet strings.  A char *** should be supplied, which upon
 229 return points to a malloced null-terminated array of char *'s
 230 containing the octet strings.  NULL is returned if the sequence is empty.
 231 .TP
 232 .SM V
 233 Sequence of octet strings with lengths.
 234 A struct berval *** should be supplied, which upon
 235 return points to a malloced null-terminated array of struct berval *'s
 236 containing the octet strings and their lengths.
 237 NULL is returned if the sequence is empty.  ber_bvecfree() can be called
 238 to free the malloced memory.
 239 .TP
 240 .SM x
 241 Skip element.  The next element is skipped.
 242 .TP
 243 .SM {
 244 Begin sequence.  No parameter is required.  The initial sequence tag
 245 and length are skipped.
 246 .TP
 247 .SM }
 248 End sequence.  No parameter is required and no action is taken.
 249 .TP
 250 .SM [
 251 Begin set.  No parameter is required.  The initial set tag
 252 and length are skipped.
 253 .TP
 254 .SM ]
 255 End set.  No parameter is required and no action is taken.
 256 .RE
 257 .LP
 258 The ber_get_int() routine tries to interpret the next element as an integer,
 259 returning the result in \fInum\fP.  The tag of whatever it finds is returned
 260 on success, -1 on failure.
 261 .LP
 262 The ber_get_stringb() routine is used to read an octet string into a
 263 preallocated buffer.  The \fIlen\fP parameter should be initialized to
 264 the size of the buffer, and will contain the length of the octet string
 265 read upon return.  The buffer should be big enough to take the octet
 266 string value plus a terminating NULL byte.
 267 .LP
 268 The ber_get_stringa() routine is used to malloc space into which an octet
 269 string is read.
 270 .LP
 271 The ber_get_stringal() routine is used to malloc space into which an octet
 272 string and its length are read.  It takes a struct berval **, and returns
 273 the result in this parameter.
 274 .LP
 275 The ber_get_null() routine is used to read a NULL element.  It returns
 276 the tag of the element it skips over.
 277 .LP
 278 The ber_get_boolean() routine is used to read a boolean value.  It is called
 279 the same way that ber_get_int() is called.
 280 .LP
 281 The ber_get_bitstringa() routine is used to read a bitstring value.  It
 282 takes a char ** which will hold the malloced bits, followed by an
 283 unsigned long *, which will point to the length (in bits) of the
 284 bitstring returned.
 285 .LP
 286 The ber_first_element() 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 ber_scanf() as follows.
 316 .LP
 317 .nf
 318       int    scope, ali, size, time, attrsonly;
 319       char   *dn, **attrs;
 320
 321       if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,
 322           &size, &time, &attrsonly, &attrs ) == -1 )
 323               /* error */
 324       else
 325               /* success */
 326 .fi
 327 .SH ERRORS
 328 If an error occurs during decoding, generally these routines return -1.
 329 .LP
 330 .SH NOTES
 331 .LP
 332 The return values for all of these functions are declared in the
 333 <lber.h> header file.  Some routines may malloc memory.
 334 .SH SEE ALSO
 335 .BR lber-encode (3)
 336 .BR ldap-parse (3)
 337 .BR ldap-sync (3)
 338 .BR ldap-async (3)
 339 .LP
 340 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
 341 Protocol", OSI-DS-26, April 1992.
 342 .LP
 343 Information Processing - Open Systems Interconnection - Model and Notation -
 344 Service Definition - Specification of Basic Encoding Rules for Abstract
 345 Syntax Notation One, International Organization for Standardization,
 346 International Standard 8825.
 347 .SH AUTHOR
 348 Tim Howes, University of Michigan
 349 .SH ACKNOWLEDGEMENTS
 350 .B      OpenLDAP
 351 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 352 .B      OpenLDAP
 353 is derived from University of Michigan LDAP 3.3 Release.