1 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 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
8 OpenLDAP LBER (liblber, -llber)
12 .BI "BerElement *ber_alloc_t(int " options ");"
14 .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
16 .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);"
18 .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
20 .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
22 .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");"
24 .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");"
26 .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");"
28 .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");"
30 .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");"
32 .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");"
34 .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");"
36 .BI "int ber_put_seq(BerElement *" ber ");"
38 .BI "int ber_put_set(BerElement *" ber ");"
41 These routines provide a subroutine interface to a simplified
42 implementation of the Basic Encoding Rules of ASN.1. The version
43 of BER these routines support is the one defined for the LDAP
44 protocol. The encoding rules are the same as BER, except that
45 only definite form lengths are used, and bitstrings and octet strings
46 are always encoded in primitive form. This
47 man page describes the encoding routines in the lber library. See
49 for details on the corresponding decoding routines. Consult
51 for information about types, allocators, and deallocators.
53 Normally, the only routines that need to be called by an application
56 to allocate a BER element for encoding,
58 to do the actual encoding, and
60 to actually write the element. The other routines are provided for those
61 applications that need more control than
64 general, these routines return the length of the element encoded, or
65 -1 if an error occurred.
69 routine is used to allocate a new BER element. It
70 should be called with an argument of LBER_USE_DER.
74 routine is used to actually write the element to a socket
75 (or file) descriptor, once it has been fully encoded (using
79 for more details on the Sockbuf implementation of the \fIsb\fP parameter.
80 If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will
81 be freed after its contents have been flushed.
85 routine is used to encode a BER element in much the same way that
87 works. One important difference, though, is
88 that some state information is kept with the \fIber\fP parameter so
89 that multiple calls can be made to
91 to append things to the end of the BER element.
93 writes to \fIber\fP, a pointer to a BerElement such as returned by
96 formats its arguments according to the format string \fIfmt\fP.
97 The format string can contain the following characters:
102 Boolean. An ber_int_t parameter should be supplied. A boolean element
106 Enumeration. An ber_int_t parameter should be supplied. An
107 enumeration element is output.
110 Integer. An ber_int_t parameter should be supplied. An integer element
114 Bitstring. A char * pointer to the start of the bitstring is supplied,
115 followed by the number of bits in the bitstring. A bitstring element
119 Null. No parameter is required. A null element is output.
122 Octet string. A char * is supplied, followed by the length of the
123 string pointed to. An octet string element is output.
126 Octet string. A struct berval * is supplied.
127 An octet string element is output.
130 Octet string. A null-terminated string is supplied. An octet string
131 element is output, not including the trailing NULL octet.
134 Tag. A ber_tag_t specifying the tag to give the next element
135 is provided. This works across calls.
138 Several octet strings. A null-terminated array of char *'s is
139 supplied. Note that a construct like '{v}' is required to get
140 an actual SEQUENCE OF octet strings.
143 Several octet strings. A null-terminated array of struct berval *'s
144 is supplied. Note that a construct like '{V}' is required to get
145 an actual SEQUENCE OF octet strings.
148 Several octet strings. An array of struct berval's is supplied. The
149 array is terminated by a struct berval with a NULL bv_val.
150 Note that a construct like '{W}' is required to get
151 an actual SEQUENCE OF octet strings.
154 Begin sequence. No parameter is required.
157 End sequence. No parameter is required.
160 Begin set. No parameter is required.
163 End set. No parameter is required.
168 routine writes the integer element \fInum\fP to the BER element \fIber\fP.
172 routine writes the enumeration element \fInum\fP to the BER element \fIber\fP.
175 .BR ber_put_boolean ()
176 routine writes the boolean value given by \fIbool\fP to the BER element.
179 .BR ber_put_bitstring ()
180 routine writes \fIblen\fP bits starting
181 at \fIstr\fP as a bitstring value to the given BER element. Note
182 that \fIblen\fP is the length \fIin bits\fP of the bitstring.
185 .BR ber_put_ostring ()
186 routine writes \fIlen\fP bytes starting at
187 \fIstr\fP to the BER element as an octet string.
190 .BR ber_put_string ()
191 routine writes the null-terminated string (minus
192 the terminating '\0') to the BER element as an octet string.
196 routine writes a NULL element to the BER element.
200 routine is used to start a sequence in the BER element. The
202 routine works similarly.
203 The end of the sequence or set is marked by the nearest matching call to
209 Assuming the following variable declarations, and that the variables
210 have been assigned appropriately, an lber encoding of
211 the following ASN.1 object:
214 AlmostASearchRequest := SEQUENCE {
215 baseObject DistinguishedName,
221 derefAliases ENUMERATED {
222 neverDerefaliases (0),
223 derefInSearching (1),
224 derefFindingBaseObj (2),
225 alwaysDerefAliases (3)
227 sizelimit INTEGER (0 .. 65535),
228 timelimit INTEGER (0 .. 65535),
230 attributes SEQUENCE OF AttributeType
234 can be achieved like so:
238 ber_int_t scope, ali, size, time, attrsonly;
242 /* ... fill in values ... */
244 ber = ber_alloc_t( LBER_USE_DER );
250 rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
251 size, time, attrsonly, attrs );
260 If an error occurs during encoding, generally these routines return -1.
264 The return values for all of these functions are declared in the
265 <lber.h> header file.
269 .BR lber-sockbuf (3),
273 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
275 is derived from University of Michigan LDAP 3.3 Release.