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_null,      ber_get_boolean,
       ber_get_bitstring, ber_first_element,  ber_next_element  -
       LBER  simplified Basic Encoding Rules library routines for
       decoding


SYNOPSIS

       #include <lber.h>

       ber_tag_t ber_get_next(
            Sockbuf *sb,
            ber_len_t *len,
            BerElement *ber);

       ber_tag_t ber_skip_tag(
            BerElement *ber,
            ber_len_t long *len);

       ber_tag_t ber_peek_tag(
            BerElement *ber,
            ber_len_t *len);

       ber_tag_t ber_scanf(
            BerElement *ber,
            const char *fmt, ...);

       ber_tag_t ber_get_int(
            BerElement *ber,
            ber_int_t *num);

       ber_tag_t ber_get_enum(
            BerElement *ber,
            ber_int_t *num);

       ber_tag_t ber_get_stringb(
            BerElement *ber,
            char *buf,
            ber_len_t *len);

       ber_tag_t ber_get_stringa(
            BerElement *ber,
            char **buf);

       ber_tag_t ber_get_stringal(
            BerElement *ber,
            struct berval **bv);

       ber_tag_t ber_get_null(
            BerElement *ber );

       ber_tag_t ber_get_boolean(
            BerElement *ber,


       ber_tag_t ber_get_bitstringa(
            BerElement *ber,
            char **buf,
            ber_len_t *blen);

       ber_tag_t ber_first_element(
            BerElement *ber,
            ber_len_t *len,
            char **cookie);

       ber_tag_t ber_next_element(
            BerElement *ber,
            ber_len_t *len,
            const char *cookie);


DESCRIPTION

       These routines provide a subroutine interface to a simpli­
       fied  implementation of the Basic Encoding Rules of ASN.1.
       The version of BER  these  routines  support  is  the  one
       defined for the LDAP protocol.  The encoding rules are the
       same as BER, except that only definite  form  lengths  are
       used,  and bitstrings and octet strings are always encoded
       in primitive form.  In  addition,  these  lightweight  BER
       routines  restrict tags and class to fit in a single octet
       (this means the actual tag must be less than 31).  When  a
       "tag" is specified in the descriptions below, it refers to
       the tag, class, and primitive or constructed  bit  in  the
       first  octet of the encoding.  This man page describes the
       decoding routines in the lber library.  See lber-encode(3)
       for  details on the corresponding encoding routines.  Con­
       sult lber-types(3) for information  about  types,  alloca­
       tors, and deallocators.

       Normally,  the  only  routines  that  need be called by an
       application are ber_get_next() to get the next BER element
       and ber_scanf() to do the actual decoding.  In some cases,
       ber_peek_tag() may also need to be called in normal usage.
       The  other  routines  are  provided for those applications
       that need more control than ber_scanf() provides.  In gen­
       eral,  these  routines  return  the  tag  of  the  element
       decoded, or -1 if an error occurred.

       The ber_get_next() routine is used to read  the  next  BER
       element from the given Sockbuf, sb.  A Sockbuf consists of
       the descriptor (usually  socket,  but  a  file  descriptor
       works  just  as well) from which to read, and a BerElement
       structure used to maintain a buffer.  On the  first  call,
       the  sb_ber  struct  should  be zeroed.  It strips off and
       returns the leading tag byte, strips off and  returns  the
       length  of  the entire element in len, and sets up ber for
       subsequent calls to ber_scanf() et al to decode  the  ele­
       ment.

       much the same way that scanf(3) works.  It reads from ber,
       a   pointer   to   a   BerElement   such  as  returned  by
       ber_get_next(), interprets the bytes according to the for­
       mat  string  fmt, and stores the results in its additional
       arguments.  The format string contains conversion specifi­
       cations which are used to direct the interpretation of the
       BER element.  The format string can contain the  following
       characters.

              a  Octet  string.   A  char  ** should be supplied.
                 Memory is allocated, filled with the contents of
                 the  octet string, null-terminated, and returned
                 in the parameter.  The caller  should  free  the
                 returned ber_val using ber_memfree().

              s  Octet  string.   A  char * buffer should be sup­
                 plied, followed by a pointer to a ber_len_t ini­
                 tialized  to  the  size  of  the  buffer.   Upon
                 return, the null-terminated octet string is  put
                 into  the  buffer, and the integer is set to the
                 actual size of the octet string.

              O  Octet string.  A struct  ber_val  **  should  be
                 supplied,  which upon return points to a dynami­
                 cally allocated  struct  berval  containing  the
                 octet  string and its length.  The caller should
                 free the returned structure using  ber_bvfree().

              o  Octet string.  A struct ber_val * should be sup­
                 plied, which upon return points  containing  the
                 dynamically   allocated  octet  string  and  its
                 length.  The caller  should  free  the  returned
                 octet string using ber_memfree().

              b  Boolean.   A  pointer  to  a ber_int_t should be
                 supplied.

              e  Enumeration.  A pointer to a ber_int_t should be
                 supplied.

              i  Integer.   A  pointer  to  a ber_int_t should be
                 supplied.

              B  Bitstring.  A char ** should be  supplied  which
                 will  point  to  the dynamically allocated bits,
                 followed by an ber_len_t *, which will point  to
                 the  length (in bits) of the bitstring returned.

              n  Null.  No parameter is required.  The element is
                 simply skipped if it is recognized.

              v  Sequence of octet strings.  A char *** should be

                 cally  allocated  null-terminated  array of char
                 *'s  containing  the  octet  strings.   NULL  is
                 returned  if  the sequence is empty.  The caller
                 should free the returned array and octet strings
                 using ber_memvfree().

              V  Sequence  of  octet  strings  with  lengths.   A
                 struct berval *** should be supplied, which upon
                 return  points  to a dynamically allocated null-
                 terminated array of struct berval *'s containing
                 the  octet  strings  and their lengths.  NULL is
                 returned if the sequence is empty.   The  caller
                 should   free   the  returned  structures  using
                 ber_bvecfree().

              l  Length of the next  element.   A  pointer  to  a
                 ber_len_t should be supplied.

              t  Tag  of  the  next  element.   A  pointer  to  a
                 ber_tag_t should be supplied.

              T  Skip element and return its tag.  A pointer to a
                 ber_tag_t should be supplied.

              x  Skip element.  The next element is skipped.

              {  Begin  sequence.  No parameter is required.  The
                 initial sequence tag and length are skipped.

              }  End sequence.  No parameter is required  and  no
                 action is taken.

              [  Begin  set.  No parameter is required.  The ini­
                 tial set tag and length are skipped.

              ]  End set.  No parameter is required and no action
                 is taken.

       The ber_get_int() routine tries to interpret the next ele­
       ment as an integer, returning the result in num.  The  tag
       of  whatever  it  finds is returned on success, LBER_ERROR
       (-1) on failure.

       The ber_get_stringb() routine is used  to  read  an  octet
       string  into  a  preallocated  buffer.   The len parameter
       should be initialized to the size of the buffer, and  will
       contain  the  length of the octet string read upon return.
       The buffer should be big enough to take the  octet  string
       value plus a terminating NULL byte.

       The ber_get_stringa() routine is used to dynamically allo­
       cate space into which an octet string is read.  The caller
       should free the returned string using ber_memfree().

       allocate space into which an octet string and  its  length
       are  read.   It  takes a struct berval **, and returns the
       result in this parameter.   The  caller  should  free  the
       returned structure using ber_bvfree().

       The ber_get_null() routine is used to read a NULL element.
       It returns the tag of the element it skips over.

       The ber_get_boolean() routine is used to  read  a  boolean
       value.   It  is  called the same way that ber_get_int() is
       called.

       The ber_get_enum() routine is used to read  a  enumeration
       value.   It  is  called the same way that ber_get_int() is
       called.

       The ber_get_bitstringa() routine is used to  read  a  bit­
       string  value.   It  takes  a  char ** which will hold the
       dynamically allocated bits, followed by  an  ber_len_t  *,
       which  will point to the length (in bits) of the bitstring
       returned.  The caller  should  free  the  returned  string
       using ber_memfree().

       The  ber_first_element() routine is used to return the tag
       and length of the first element in a set or sequence.   It
       also  returns  in  cookie  a  magic  cookie parameter that
       should be passed  to  subsequent  calls  to  ber_next_ele­
       ment(), which returns similar information.


EXAMPLES

       Assume  the variable ber contains a lightweight BER encod­
       ing of the following ASN.1 object:

             AlmostASearchRequest := SEQUENCE {
                 baseObject      DistinguishedName,
                 scope           ENUMERATED {
                     baseObject    (0),
                     singleLevel   (1),
                     wholeSubtree  (2)
                 },
                 derefAliases    ENUMERATED {
                     neverDerefaliases   (0),
                     derefInSearching    (1),
                     derefFindingBaseObj (2),
                     alwaysDerefAliases  (3)
                 },
                 sizelimit       INTEGER (0 .. 65535),
                 timelimit       INTEGER (0 .. 65535),
                 attrsOnly       BOOLEAN,
                 attributes      SEQUENCE OF AttributeType
             }

       The element can be decoded using ber_scanf() as follows.

             char   *dn, **attrs;
             ber_tag_t tag;

             tag = ber_scanf( ber, "{aeeiib{v}}",
                 &dn, &scope, &deref,
                 &size, &time, &attrsonly, &attrs );

             if( tag == LBER_ERROR ) {
                     /* error */
             } else {
                     /* success */
             }

             ber_memfree( dn );
             ber_memvfree( attrs );


ERRORS

       If an error occurs during decoding, generally  these  rou­
       tines return LBER_ERROR (-1).


NOTES

       The  return values for all of these functions are declared
       in the <lber.h> header file.  Some  routines  may  dynami­
       cally  allocate  memory  which must be freed by the caller
       using supplied deallocation routines.


SEE ALSO

       lber-encode(3) lber-memory(3) lber-types(3)  ldap-parse(3)
       ldap-sync(3) ldap-async(3)


ACKNOWLEDGEMENTS

       OpenLDAP  is developed and maintained by The OpenLDAP Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html