1 .TH LBER-ENCODE 3 "15 June 1992"
3 ber_alloc, ber_flush, ber_printf, ber_put_int, 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
13 typedef struct berelement {
17 struct seqorset *ber_sos;
26 typedef struct sockbuf {
35 BerElement *ber_alloc()
41 ber_flush(sb, ber, freeit)
50 ber_printf(ber, fmt [, arg... ] )
58 ber_put_int(ber, num, tag)
67 ber_put_ostring(ber, str, len, tag)
77 ber_put_string(ber, str, tag)
86 ber_put_null(ber, tag)
94 ber_put_boolean(ber, bool, tag)
103 ber_put_bitstring(ber, str, blen, tag)
113 ber_start_seq(ber, tag)
121 ber_start_set(ber, tag)
140 These routines provide a subroutine interface to a simplified
141 implementation of the Basic Encoding Rules of ASN.1. The version
142 of BER these routines support is the one defined for the LDAP
143 protocol. The encoding rules are the same as BER, except that
144 only definite form lengths are used, and bitstrings and octet strings
145 are always encoded in primitive form. In addition, these lightweight
146 BER routines restrict tags and class to fit in a single octet (this
147 means the actual tag must be less than 31). When a "tag" is specified
148 in the descriptions below, it refers to the tag, class, and primitive
149 or constructed bit in the first octet of the encoding. This
150 man page describes the encoding routines in the lber library. See
151 lber-decode(3) for details on the corresponding decoding routines.
153 Normally, the only routines that need be called by an application
154 are ber_alloc() to allocate a BER element for encoding, ber_printf()
155 to do the actual encoding, and ber_flush() to actually write the
156 element. The other routines are provided for those
157 applications that need more control than ber_printf() provides. In
158 general, these routines return the length of the element encoded, or
159 -1 if an error occurred.
161 The ber_alloc() routine is used to allocate a new BER element. The
162 ber_flush() routine is used to actually write the element to a socket
163 (or file) descriptor, once it has been fully encoded (using ber_printf()
164 and friends). The \fIsb\fP structure contains the descriptor and a
165 BerElement used for input buffering. Only the \fIsb_sd\fP field is relevant
166 to the ber_flush() routine.
168 The ber_printf() routine is used to encode a BER element in much the
169 same way that sprintf(3) works. One important difference, though, is
170 that some state information is kept with the \fIber\fP parameter so
171 that multiple calls can be made to ber_printf() to append things to
172 the end of the BER element. Ber_printf() writes to \fIber\fP, a pointer to a
173 BerElement such as returned by ber_alloc(). It interprets and
174 formats its arguments according to the format string \fIfmt\fP.
175 The format string can contain the following characters:
180 Boolean. An integer parameter should be supplied. A boolean element
184 Integer. An integer parameter should be supplied. An integer element
188 Bitstring. A char * pointer to the start of the bitstring is supplied,
189 followed by the number of bits in the bitstring. A bitstring element
193 Null. No parameter is required. A null element is output.
196 Octet string. A char * is supplied, followed by the length of the
197 string pointed to. An octet string element is output.
200 Octet string. A null-terminated string is supplied. An octet string
201 element is output, not including the trailing NULL octet.
204 Tag. An int specifying the tag to give the next element is provided.
205 This works across calls.
208 Several octet strings. A null-terminated array of char *'s is
209 supplied. Note that a construct like '{v}' is required to get
210 an actual SEQUENCE OF octet strings.
213 Begin sequence. No parameter is required.
216 End sequence. No parameter is required.
219 Begin set. No parameter is required.
222 End set. No parameter is required.
225 The ber_put_int() routine writes the integer element \fInum\fP to
226 the BER element \fIber\fP.
228 The ber_put_boolean() routine writes the boolean value given by
229 \fIbool\fP to the BER element.
231 The ber_put_bitstring() routine writes \fIblen\fP bits starting
232 at \fIstr\fP as a bitstring value to the given BER element. Note
233 that \fIblen\fP is the length \fIin bits\fP of the bitstring.
235 The ber_put_ostring() routine writes \fIlen\fP bytes starting at
236 \fIstr\fP to the BER element as an octet string.
238 The ber_put_string() routine writes the null-terminated string (minus
239 the terminating '\0') to the BER element as an octet string.
241 The ber_put_null() routine writes a NULL element to the BER element.
243 The ber_start_seq() routine is used to start a sequence in the BER
244 element. The ber_start_set() routine works similarly.
245 The end of the sequence or set is marked by the nearest matching
246 call to ber_put_seq() or ber_put_set(), respectively.
248 The ber_first_element() routine is used to return the tag and length
249 of the first element in a set or sequence. It also returns in \fIcookie\fP
250 a magic cookie parameter that should be passed to subsequent calls to
251 ber_next_element(), which returns similar information.
253 Assuming the following variable declarations, and that the variables
254 have been assigned appropriately, an lber encoding of
255 the following ASN.1 object:
258 AlmostASearchRequest := SEQUENCE {
259 baseObject DistinguishedName,
265 derefAliases ENUMERATED {
266 neverDerefaliases (0),
267 derefInSearching (1),
268 derefFindingBaseObj (2),
269 alwaysDerefAliases (3)
271 sizelimit INTEGER (0 .. 65535),
272 timelimit INTEGER (0 .. 65535),
274 attributes SEQUENCE OF AttributeType
278 can be achieved like so:
281 int scope, ali, size, time, attrsonly;
284 /* ... fill in values ... */
285 if ( (ber = ber_alloc()) == NULLBER )
288 if ( ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
289 size, time, attrsonly, attrs ) == -1 )
295 If an error occurs during encoding, generally these routines return -1.
299 The return values for all of these functions are declared in the
300 <lber.h> header file.
307 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
308 Protocol", OSI-DS-26, April 1992.
310 Information Processing - Open Systems Interconnection - Model and Notation -
311 Service Definition - Specification of Basic Encoding Rules for Abstract
312 Syntax Notation One, International Organization for Standardization,
313 International Standard 8825.
315 Tim Howes, University of Michigan