LBER_ENCODE(3) LBER_ENCODE(3)
NAME
ber_alloc_t, ber_flush, ber_flush2, 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 - OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding
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_flush2(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 of BER these routines support is the one defined for the LDAP protocol. The encod- ing rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primi- tive form. This man page describes the encoding routines in 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, ber_printf() to do the actual encoding, and ber_flush2() to actually write 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 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_flush2() 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). 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. If LBER_FLUSH_FREE_ON_SUC- CESS is used, the ber is only freed when successfully flushed, other- wise it is left intact; if LBER_FLUSH_FREE_ON_ERROR is used, the ber is only freed when an error occurs, otherwise it is left intact; if LBER_FLUSH_FREE_ALWAYS is used, the ber is freed anyway. This function differs from the original ber_flush(3) function, whose behavior corre- sponds to that indicated for LBER_FLUSH_FREE_ON_SUCCESS. Note that in the future, the behavior of ber_flush(3) with freeit non-zero might change into that of ber_flush2(3) with freeit set to LBER_FLUSH_FREE_ALWAYS. The ber_printf() routine is used to encode a BER element 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 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 fmt. The format string 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 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 supplied. 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. 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 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 ele- ment. The ber_start_set() routine works similarly. The end of the sequence or set 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 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 routines 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-sockbuf(3), lber-types(3)
ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni- versity of Michigan LDAP 3.3 Release. OpenLDAP 2.4.50 2020/04/28 LBER_ENCODE(3)
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.