1.lf 1 stdin
2.TH LBER_ENCODE 3 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
5.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
6.SH NAME
7ber_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
8.SH LIBRARY
9OpenLDAP LBER (liblber, \-llber)
10.SH SYNOPSIS
11.B #include <lber.h>
12.LP
13.BI "BerElement *ber_alloc_t(int " options ");"
14.LP
15.BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
16.LP
17.BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
18.LP
19.BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);"
20.LP
21.BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
22.LP
23.BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
24.LP
25.BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");"
26.LP
27.BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");"
28.LP
29.BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");"
30.LP
31.BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");"
32.LP
33.BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");"
34.LP
35.BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");"
36.LP
37.BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");"
38.LP
39.BI "int ber_put_seq(BerElement *" ber ");"
40.LP
41.BI "int ber_put_set(BerElement *" ber ");"
42.SH DESCRIPTION
43.LP
44These routines provide a subroutine interface to a simplified
45implementation of the Basic Encoding Rules of ASN.1.  The version
46of BER these routines support is the one defined for the LDAP
47protocol.  The encoding rules are the same as BER, except that 
48only definite form lengths are used, and bitstrings and octet strings
49are always encoded in primitive form.  This
50man page describes the encoding routines in the lber library.  See
51.BR lber-decode (3)
52for details on the corresponding decoding routines.  Consult
53.BR lber-types (3)
54for information about types, allocators, and deallocators.
55.LP
56Normally, the only routines that need to be called by an application
57are
58.BR ber_alloc_t ()
59to allocate a BER element for encoding,
60.BR ber_printf ()
61to do the actual encoding, and
62.BR ber_flush2 ()
63to actually write the element.  The other routines are provided for those
64applications that need more control than
65.BR ber_printf ()
66provides.  In
67general, these routines return the length of the element encoded, or
68\-1 if an error occurred.
69.LP
70The
71.BR ber_alloc_t ()
72routine is used to allocate a new BER element.  It
73should be called with an argument of LBER_USE_DER.
74.LP
75The
76.BR ber_flush2 ()
77routine is used to actually write the element to a socket
78(or file) descriptor, once it has been fully encoded (using
79.BR ber_printf ()
80and friends).  See
81.BR lber-sockbuf (3)
82for more details on the Sockbuf implementation of the \fIsb\fP parameter.
83If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will
84be freed.
85If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed
86when successfully flushed, otherwise it is left intact;
87if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed
88when an error occurs, otherwise it is left intact;
89if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway.
90This function differs from the original
91.BR ber_flush (3)
92function, whose behavior corresponds to that indicated
93for \fILBER_FLUSH_FREE_ON_SUCCESS\fP.
94Note that in the future, the behavior of
95.BR ber_flush (3)
96with \fIfreeit\fP non-zero might change into that of
97.BR ber_flush2 (3)
98with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP.
99.LP
100The
101.BR ber_printf ()
102routine is used to encode a BER element in much the same way that
103.BR sprintf (3)
104works.  One important difference, though, is
105that some state information is kept with the \fIber\fP parameter so
106that multiple calls can be made to
107.BR ber_printf ()
108to append things to the end of the BER element.
109.BR Ber_printf ()
110writes to \fIber\fP, a pointer to a BerElement such as returned by
111.BR ber_alloc_t ().
112It interprets and
113formats its arguments according to the format string \fIfmt\fP.
114The format string can contain the following characters:
115.RS
116.LP
117.TP 3
118.B b
119Boolean.  An ber_int_t parameter should be supplied.  A boolean element
120is output.
121.TP
122.B e
123Enumeration.  An ber_int_t parameter should be supplied.  An
124enumeration element is output.
125.TP
126.B i
127Integer.  An ber_int_t parameter should be supplied.  An integer element
128is output.
129.TP
130.B B
131Bitstring.  A char * pointer to the start of the bitstring is supplied,
132followed by the number of bits in the bitstring.  A bitstring element
133is output.
134.TP
135.B n
136Null.  No parameter is required.  A null element is output.
137.TP
138.B o
139Octet string.  A char * is supplied, followed by the length of the
140string pointed to.  An octet string element is output.
141.TP
142.B O
143Octet string.  A struct berval * is supplied.
144An octet string element is output.
145.TP
146.B s
147Octet string.  A null-terminated string is supplied.  An octet string
148element is output, not including the trailing NULL octet.
149.TP
150.B t
151Tag.  A ber_tag_t specifying the tag to give the next element
152is provided.  This works across calls.
153.TP
154.B v
155Several octet strings.  A null-terminated array of char *'s is
156supplied.  Note that a construct like '{v}' is required to get
157an actual SEQUENCE OF octet strings.
158.TP
159.B V
160Several octet strings.  A null-terminated array of struct berval *'s
161is supplied.  Note that a construct like '{V}' is required to get
162an actual SEQUENCE OF octet strings.
163.TP
164.B W
165Several octet strings.  An array of struct berval's is supplied.  The
166array is terminated by a struct berval with a NULL bv_val.
167Note that a construct like '{W}' is required to get
168an actual SEQUENCE OF octet strings.
169.TP
170.B {
171Begin sequence.  No parameter is required.
172.TP
173.B }
174End sequence.  No parameter is required.
175.TP
176.B [
177Begin set.  No parameter is required.
178.TP
179.B ]
180End set.  No parameter is required.
181.RE
182.LP
183The
184.BR ber_put_int ()
185routine writes the integer element \fInum\fP to the BER element \fIber\fP.
186.LP
187The
188.BR ber_put_enum ()
189routine writes the enumeration element \fInum\fP to the BER element \fIber\fP.
190.LP
191The
192.BR ber_put_boolean ()
193routine writes the boolean value given by \fIbool\fP to the BER element.
194.LP
195The
196.BR ber_put_bitstring ()
197routine writes \fIblen\fP bits starting
198at \fIstr\fP as a bitstring value to the given BER element.  Note
199that \fIblen\fP is the length \fIin bits\fP of the bitstring.
200.LP
201The
202.BR ber_put_ostring ()
203routine writes \fIlen\fP bytes starting at
204\fIstr\fP to the BER element as an octet string.
205.LP
206The
207.BR ber_put_string ()
208routine writes the null-terminated string (minus
209the terminating '\0') to the BER element as an octet string.
210.LP
211The
212.BR ber_put_null ()
213routine writes a NULL element to the BER element.
214.LP
215The
216.BR ber_start_seq ()
217routine is used to start a sequence in the BER element.  The
218.BR ber_start_set ()
219routine works similarly.
220The end of the sequence or set is marked by the nearest matching call to
221.BR ber_put_seq ()
222or
223.BR ber_put_set (),
224respectively.
225.SH EXAMPLES
226Assuming the following variable declarations, and that the variables
227have been assigned appropriately, an lber encoding of
228the following ASN.1 object:
229.LP
230.nf
231      AlmostASearchRequest := SEQUENCE {
232          baseObject      DistinguishedName,
233          scope           ENUMERATED {
234              baseObject    (0),
235              singleLevel   (1),
236              wholeSubtree  (2)
237          },
238          derefAliases    ENUMERATED {
239              neverDerefaliases   (0),
240              derefInSearching    (1),
241              derefFindingBaseObj (2),
242              alwaysDerefAliases  (3)
243          },
244          sizelimit       INTEGER (0 .. 65535),
245          timelimit       INTEGER (0 .. 65535),
246          attrsOnly       BOOLEAN,
247          attributes      SEQUENCE OF AttributeType
248      }
249.fi
250.LP
251can be achieved like so:
252.LP
253.nf
254      int rc;
255      ber_int_t    scope, ali, size, time, attrsonly;
256      char   *dn, **attrs;
257      BerElement *ber;
258
259      /* ... fill in values ... */
260
261      ber = ber_alloc_t( LBER_USE_DER );
262
263      if ( ber == NULL ) {
264              /* error */
265      }
266
267      rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
268          size, time, attrsonly, attrs );
269
270      if( rc == \-1 ) {
271              /* error */
272      } else {
273              /* success */
274      }
275.fi
276.SH ERRORS
277If an error occurs during encoding, generally these routines return \-1.
278.LP
279.SH NOTES
280.LP
281The return values for all of these functions are declared in the
282<lber.h> header file.
283.SH SEE ALSO
284.BR lber-decode (3),
285.BR lber-memory (3),
286.BR lber-sockbuf (3),
287.BR lber-types (3)
288.SH ACKNOWLEDGEMENTS
289.lf 1 ./../Project
290.\" Shared Project Acknowledgement Text
291.B "OpenLDAP Software"
292is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
293.B "OpenLDAP Software"
294is derived from the University of Michigan LDAP 3.3 Release.  
295.lf 289 stdin
296