1LBER_ENCODE(3)             Library Functions Manual             LBER_ENCODE(3)
2
3
4

NAME

6       ber_alloc_t,    ber_flush,    ber_flush2,    ber_printf,   ber_put_int,
7       ber_put_enum,    ber_put_ostring,     ber_put_string,     ber_put_null,
8       ber_put_boolean,   ber_put_bitstring,   ber_start_seq,   ber_start_set,
9       ber_put_seq, ber_put_set -  OpenLDAP  LBER  simplified  Basic  Encoding
10       Rules library routines for encoding
11

LIBRARY

13       OpenLDAP LBER (liblber, -llber)
14

SYNOPSIS

16       #include <lber.h>
17
18       BerElement *ber_alloc_t(int options);
19
20       int ber_flush(Sockbuf *sb, BerElement *ber, int freeit);
21
22       int ber_flush2(Sockbuf *sb, BerElement *ber, int freeit);
23
24       int ber_printf(BerElement *ber, const char *fmt, ...);
25
26       int ber_put_int(BerElement *ber, ber_int_t num, ber_tag_t tag);
27
28       int ber_put_enum(BerElement *ber, ber_int_t num, ber_tag_t tag);
29
30       int  ber_put_ostring(BerElement  *ber,  const char *str, ber_len_t len,
31       ber_tag_t tag);
32
33       int ber_put_string(BerElement *ber, const char *str, ber_tag_t tag);
34
35       int ber_put_null(BerElement *ber, ber_tag_t tag);
36
37       int ber_put_boolean(BerElement *ber, ber_int_t bool, ber_tag_t tag);
38
39       int ber_put_bitstring(BerElement *ber, const char *str, ber_len_t blen,
40       ber_tag_t tag);
41
42       int ber_start_seq(BerElement *ber, ber_tag_t tag);
43
44       int ber_start_set(BerElement *ber, ber_tag_t tag);
45
46       int ber_put_seq(BerElement *ber);
47
48       int ber_put_set(BerElement *ber);
49

DESCRIPTION

51       These routines provide a subroutine interface to a simplified implemen‐
52       tation of the Basic Encoding Rules of ASN.1.  The version of BER  these
53       routines  support is the one defined for the LDAP protocol.  The encod‐
54       ing rules are the same as BER, except that only definite  form  lengths
55       are used, and bitstrings and octet strings are always encoded in primi‐
56       tive form.  This man page describes the encoding routines in  the  lber
57       library.   See lber-decode(3) for details on the corresponding decoding
58       routines.  Consult lber-types(3) for information about  types,  alloca‐
59       tors, and deallocators.
60
61       Normally,  the  only  routines that need to be called by an application
62       are ber_alloc_t() to allocate a BER element for encoding,  ber_printf()
63       to  do the actual encoding, and ber_flush2() to actually write the ele‐
64       ment.  The other routines are provided for those applications that need
65       more  control  than  ber_printf() provides.  In general, these routines
66       return the length of the element encoded, or -1 if an error occurred.
67
68       The ber_alloc_t() routine is used to allocate a new  BER  element.   It
69       should be called with an argument of LBER_USE_DER.
70
71       The  ber_flush2()  routine  is  used to actually write the element to a
72       socket (or file) descriptor, once it  has  been  fully  encoded  (using
73       ber_printf() and friends).  See lber-sockbuf(3) for more details on the
74       Sockbuf implementation of the sb parameter.  If the freeit parameter is
75       non-zero,  the  supplied ber will be freed.  If LBER_FLUSH_FREE_ON_SUC‐
76       CESS is used, the ber is only freed when successfully  flushed,  other‐
77       wise it is left intact; if LBER_FLUSH_FREE_ON_ERROR is used, the ber is
78       only freed when an error  occurs,  otherwise  it  is  left  intact;  if
79       LBER_FLUSH_FREE_ALWAYS is used, the ber is freed anyway.  This function
80       differs from the original ber_flush(3) function, whose behavior  corre‐
81       sponds  to that indicated for LBER_FLUSH_FREE_ON_SUCCESS.  Note that in
82       the future, the behavior of ber_flush(3)  with  freeit  non-zero  might
83       change    into    that    of   ber_flush2(3)   with   freeit   set   to
84       LBER_FLUSH_FREE_ALWAYS.
85
86       The ber_printf() routine is used to encode a BER element  in  much  the
87       same  way  that sprintf(3) works.  One important difference, though, is
88       that some state information is kept with the ber parameter so that mul‐
89       tiple  calls can be made to ber_printf() to append things to the end of
90       the BER element.  Ber_printf() writes to ber, a pointer to a BerElement
91       such as returned by ber_alloc_t().  It interprets and formats its argu‐
92       ments according to the format string fmt.  The format string  can  con‐
93       tain the following characters:
94
95              b  Boolean.  An ber_int_t parameter should be supplied.  A bool‐
96                 ean element is output.
97
98              e  Enumeration.  An ber_int_t parameter should be supplied.   An
99                 enumeration element is output.
100
101              i  Integer.   An ber_int_t parameter should be supplied.  An in‐
102                 teger element is output.
103
104              B  Bitstring.  A char * pointer to the start of the bitstring is
105                 supplied, followed by the number of bits in the bitstring.  A
106                 bitstring element is output.
107
108              n  Null.  No parameter is required.  A null element is output.
109
110              o  Octet string.  A char * is supplied, followed by  the  length
111                 of the string pointed to.  An octet string element is output.
112
113              O  Octet  string.   A  struct  berval  *  is supplied.  An octet
114                 string element is output.
115
116              s  Octet string.  A  null-terminated  string  is  supplied.   An
117                 octet  string  element  is output, not including the trailing
118                 NULL octet.
119
120              t  Tag.  A ber_tag_t specifying the tag to give the next element
121                 is provided.  This works across calls.
122
123              v  Several  octet  strings.  A null-terminated array of char *'s
124                 is supplied.  Note that a construct like '{v}' is required to
125                 get an actual SEQUENCE OF octet strings.
126
127              V  Several  octet  strings.   A  null-terminated array of struct
128                 berval *'s is supplied.  Note that a construct like '{V}'  is
129                 required to get an actual SEQUENCE OF octet strings.
130
131              W  Several  octet  strings.  An array of struct berval's is sup‐
132                 plied.  The array is terminated by a  struct  berval  with  a
133                 NULL bv_val.  Note that a construct like '{W}' is required to
134                 get an actual SEQUENCE OF octet strings.
135
136              {  Begin sequence.  No parameter is required.
137
138              }  End sequence.  No parameter is required.
139
140              [  Begin set.  No parameter is required.
141
142              ]  End set.  No parameter is required.
143
144       The ber_put_int() routine writes the integer element num to the BER el‐
145       ement ber.
146
147       The  ber_put_enum()  routine  writes the enumeration element num to the
148       BER element ber.
149
150       The ber_put_boolean() routine writes the boolean value given by bool to
151       the BER element.
152
153       The  ber_put_bitstring()  routine writes blen bits starting at str as a
154       bitstring value to the given BER element.  Note that blen is the length
155       in bits of the bitstring.
156
157       The  ber_put_ostring()  routine writes len bytes starting at str to the
158       BER element as an octet string.
159
160       The ber_put_string() routine writes the null-terminated  string  (minus
161       the terminating ' ') to the BER element as an octet string.
162
163       The ber_put_null() routine writes a NULL element to the BER element.
164
165       The ber_start_seq() routine is used to start a sequence in the BER ele‐
166       ment.  The ber_start_set() routine works similarly.  The end of the se‐
167       quence  or  set is marked by the nearest matching call to ber_put_seq()
168       or ber_put_set(), respectively.
169

EXAMPLES

171       Assuming the following variable declarations, and  that  the  variables
172       have  been  assigned  appropriately,  an lber encoding of the following
173       ASN.1 object:
174
175             AlmostASearchRequest := SEQUENCE {
176                 baseObject      DistinguishedName,
177                 scope           ENUMERATED {
178                     baseObject    (0),
179                     singleLevel   (1),
180                     wholeSubtree  (2)
181                 },
182                 derefAliases    ENUMERATED {
183                     neverDerefaliases   (0),
184                     derefInSearching    (1),
185                     derefFindingBaseObj (2),
186                     alwaysDerefAliases  (3)
187                 },
188                 sizelimit       INTEGER (0 .. 65535),
189                 timelimit       INTEGER (0 .. 65535),
190                 attrsOnly       BOOLEAN,
191                 attributes      SEQUENCE OF AttributeType
192             }
193
194       can be achieved like so:
195
196             int rc;
197             ber_int_t    scope, ali, size, time, attrsonly;
198             char   *dn, **attrs;
199             BerElement *ber;
200
201             /* ... fill in values ... */
202
203             ber = ber_alloc_t( LBER_USE_DER );
204
205             if ( ber == NULL ) {
206                     /* error */
207             }
208
209             rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
210                 size, time, attrsonly, attrs );
211
212             if( rc == -1 ) {
213                     /* error */
214             } else {
215                     /* success */
216             }
217

ERRORS

219       If an error occurs during encoding, generally these routines return -1.
220

NOTES

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

SEE ALSO

226       lber-decode(3), lber-memory(3), lber-sockbuf(3), lber-types(3)
227

ACKNOWLEDGEMENTS

229       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
230       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
231       versity of Michigan LDAP 3.3 Release.
232
233
234
235OpenLDAP 2.4.57                   2021/01/18                    LBER_ENCODE(3)
Impressum