ber_alloc_t,     ber_flush,    ber_printf,    ber_put_int,
       ber_put_enum,       ber_put_ostring,       ber_put_string,
       ber_put_null,      ber_put_boolean,     ber_put_bitstring,
       ber_start_seq, ber_start_set, ber_put_seq,  ber_put_set  -
       LBER  simplified Basic Encoding Rules library routines for
       encoding


SYNOPSIS

       #include <lber.h>

       BerElement *ber_alloc_t( int options );

       int ber_flush(
            Sockbuf *sb,
            BerElement *ber,
            int freeit);

       int ber_printf(
            BerElement *ber,
            const char *fmt, ...);

       int ber_put_int(
            BerElement *ber,
            ber_int_t num,
            ber_tag_t tag);

       int ber_put_enum(
            BerElement *ber,
            ber_int_t num,
            ber_tag_t tag);

       int ber_put_ostring(
            BerElement *ber,
            const char *str,
            ber_len_t long len,
            ber_tag_t tag);

       int ber_put_string(
            BerElement *ber,
            const char *str,
            ber_tag_t tag);

       int ber_put_null(
            BerElement *ber;
            ber_tag_t tag);

       int ber_put_boolean(
            BerElement *ber;
            ber_int_t bool;
            ber_tag_t tag;

       int ber_put_bitstring(
            BerElement *ber,

            ber_len_t blen,
            ber_tag_t tag);

       int ber_start_seq(
            BerElement *ber,
            ber_tag_t tag);

       int ber_start_set(
            BerElement *ber,
            ber_tag_t tag);

       int ber_put_seq(
            BerElement *ber);

       int ber_put_set(
            BerElement *ber);


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
       encoding routines in the lber library.  See lber-decode(3)
       for  details on the corresponding decoding 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_alloc_t() to allocate  a  BER  element
       for  encoding, ber_printf() to do the actual encoding, and
       ber_flush() to actually write the element.  The other rou­
       tines  are  provided for those applications that need more
       control than ber_printf()  provides.   In  general,  these
       routines  return  the length of the element encoded, or -1
       if an error occurred.

       The ber_alloc_t() routine is used to allocate  a  new  BER
       element.    It  should  be  called  with  an  argument  of
       LBER_USE_DER.  The ber_flush() routine is used to actually
       write  the  element to a socket (or file) descriptor, once
       it  has  been  fully  encoded  (using   ber_printf()   and
       friends).   The sb structure contains the descriptor and a
       BerElement used for input buffering.  Only the sb_sd field
       is relevant to the ber_flush() routine.

       in much the same way that sprintf(3) works.  One important
       difference, though, is that some state information is kept
       with the ber parameter so that multiple calls can be  made
       to  ber_printf()  to  append  things to the end of the BER
       element.  Ber_printf() writes  to  ber,  a  pointer  to  a
       BerElement such as returned by ber_alloc().  It interprets
       and formats its arguments according to the  format  string
       fmt.   The format string can contain the following charac­
       ters:

              b  Boolean.  An ber_int_t parameter should be  sup­
                 plied.  A boolean element is output.

              e  Enumeration.   An  ber_int_t parameter should be
                 supplied.  An enumeration element is output.

              i  Integer.  An ber_int_t parameter should be  sup­
                 plied.  An integer element is output.

              B  Bitstring.  A char * pointer to the start of the
                 bitstring is supplied, followed by the number of
                 bits  in  the bitstring.  A bitstring element is
                 output.

              n  Null.  No parameter is required.  A null element
                 is output.

              o  Octet string.  A char * is supplied, followed by
                 the length of the string pointed to.   An  octet
                 string element is output.

              O  Octet  string.   A  struct berval * is supplied.
                 An octet string element is output.

              s  Octet string.  A null-terminated string is  sup­
                 plied.   An  octet string element is output, not
                 including the trailing NULL octet.

              t  Tag.  A ber_tag_t specifying the tag to give the
                 next  element  is  provided.   This works across
                 calls.

              v  Several octet strings.  A null-terminated  array
                 of  char *'s is supplied.  Note that a construct
                 like '{v}' is required to get an actual SEQUENCE
                 OF octet strings.

              V  Several  octet strings.  A null-terminated array
                 of struct berval *'s is supplied.  Note  that  a
                 construct  like  '{V}'  is  required  to  get an
                 actual SEQUENCE OF octet strings.


              }  End sequence.  No parameter is required.

              [  Begin set.  No parameter is required.

              ]  End set.  No parameter is required.

       The ber_put_int() routine writes the integer  element  num
       to the BER element ber.

       The ber_put_enum() routine writes the enumberation element
       num to the BER element ber.

       The ber_put_boolean() routine  writes  the  boolean  value
       given by bool to the BER element.

       The  ber_put_bitstring() routine writes blen bits starting
       at str as a bitstring value  to  the  given  BER  element.
       Note that blen is the length in bits of the bitstring.

       The ber_put_ostring() routine writes len bytes starting at
       str to the BER element as an octet string.

       The ber_put_string() routine  writes  the  null-terminated
       string  (minus  the terminating ' ') to the BER element as
       an octet string.

       The ber_put_null() routine writes a NULL  element  to  the
       BER element.

       The ber_start_seq() routine is used to start a sequence in
       the BER element.  The ber_start_set() routine works  simi­
       larly.   The  end  of the sequence or set is marked by the
       nearest matching call to ber_put_seq()  or  ber_put_set(),
       respectively.

       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

       Assuming the following variable declarations, and that the
       variables have been assigned appropriately, an lber 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
             }

       can be achieved like so:

             int rc;
             ber_int_t    scope, ali, size, time, attrsonly;
             char   *dn, **attrs;
             BerElement *ber;

             /* ... fill in values ... */

             ber = ber_alloc_t( LBER_USE_DER );

             if ( ber == NULL ) {
                 /* error */
             }

             rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
                 size, time, attrsonly, attrs );

             if( rc == -1 ) {
                     /* error */
             } else {
                     /* success */
             }


ERRORS

       If  an  error occurs during encoding, generally these rou­
       tines return -1.


NOTES

       The return values for all of these functions are  declared
       in the <lber.h> header file.


SEE ALSO

       lber-decode(3)  lber-memory(3) lber-types(3) ldap-async(3)
       ldap-sync(3) ldap-parse(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