LBER_ENCODE(3) LBER_ENCODE(3)
NAME
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(3,n)
LIBRARY
OpenLDAP LBER (liblber, -llber)
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 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, const char *str, 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 simplified implemen-
tation of the Basic Encoding Rules of ASN.1. The version(1,3,5) of BER these
routines support is the one defined for the LDAP protocol. The encod-
ing(3,n) rules are the same as BER, except that only definite form lengths
are used, and bitstrings and octet strings are always encoded in(1,8) primi-
tive form. This man(1,5,7) page describes the encoding(3,n) routines in(1,8) the lber
library. See lber-decode(3) for details on the corresponding decoding
routines. Consult lber-types(3) for information about types, alloca-
tors, and deallocators.
Normally, the only routines that need to be called by an application
are ber_alloc_t() to allocate a BER element for encoding(3,n), ber_printf()
to do the actual encoding(3,n), and ber_flush() to actually write(1,2) the ele-
ment. The other routines 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(3,n) an error(8,n) 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(1,2) the element to a
socket(2,7,n) (or file(1,n)) descriptor, once it has been fully encoded (using
ber_printf() and friends). See lber-sockbuf(3) for more details on the
Sockbuf implementation of the sb parameter. If the freeit parameter is
non-zero, the supplied ber will be freed after its contents have been
flushed.
The ber_printf() routine is used to encode a BER element in(1,8) 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 mul-
tiple 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_t(). It interprets and formats its argu-
ments according to the format string(3,n) fmt. The format string(3,n) can con-
tain the following characters:
b Boolean. An ber_int_t parameter should be supplied. 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 supplied. 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(1,8) 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(3,n) pointed to. An octet string(3,n) element is output.
O Octet string. A struct berval * is supplied. An octet
string(3,n) element is output.
s Octet string. A null-terminated string(3,n) is supplied. An
octet string(3,n) 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.
W Several octet strings. An array of struct berval's is sup-
plied. The array is terminated by a struct berval with a
NULL bv_val. Note that a construct like '{W}' is required to
get an actual SEQUENCE OF octet strings.
{ Begin sequence. No parameter is required.
} 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 enumeration 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(1,8) 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(3,n) (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(1,8) the BER ele-
ment. The ber_start_set() routine works similarly. The end of the
sequence or set(7,n,1 builtins) is marked by the nearest matching call to ber_put_seq()
or ber_put_set(), respectively.
EXAMPLES
Assuming the following variable declarations, and that the variables
have been assigned appropriately, an lber encoding(3,n) 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(1,2,n), attrsonly;
char *dn, **attrs;
BerElement *ber;
/* ... fill in(1,8) values ... */
ber = ber_alloc_t( LBER_USE_DER );
if(3,n) ( ber == NULL ) {
/* error(8,n) */
}
rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
size, time(1,2,n), attrsonly, attrs );
if(3,n)( rc == -1 ) {
/* error(8,n) */
} else {
/* success */
}
ERRORS
If an error(8,n) occurs during encoding(3,n), generally these routines return -1.
NOTES
The return values for all of these functions are declared in(1,8) the
<lber.h> header file.
SEE ALSO
lber-decode(3), lber-memory(3), lber-sockbuf(3), lber-types(3)
ACKNOWLEDGEMENTS
OpenLDAP is developed and maintained by The OpenLDAP Project
(http://www.openldap.org/). OpenLDAP is derived from University of
Michigan LDAP 3.3 Release.
OpenLDAP LDVERSION RELEASEDATE LBER_ENCODE(3)