ber_free(3ldap)

1ber_decode(3LDAP)           LDAP Library Functions           ber_decode(3LDAP)
2
3
4

NAME

6       ber_decode,  ber_alloc_t,  ber_free,  ber_bvdup, ber_init, ber_flatten,
7       ber_get_next,  ber_skip_tag,  ber_peek_tag,   ber_scanf,   ber_get_int,
8       ber_get_stringa,   ber_get_stringal,   ber_get_stringb,   ber_get_null,
9       ber_get_boolean,  ber_get_bitstring,  ber_first_element,  ber_next_ele‐
10       ment,  ber_bvfree, ber_bvecfree - Basic Encoding Rules library decoding
11       functions
12

SYNOPSIS

14       cc[ flag... ] file... -lldap[ library... ]
15       #include <lber.h>
16
17       BerElement *ber_alloc_t(int options);
18
19
20       struct berval *ber_bvdup(const struct berval *bv);
21
22
23       void ber_free(BerElement *ber, int freebuf);
24
25
26       BerElement *ber_init(const struct berval *bv);
27
28
29       int ber_flatten(BerElement *ber, struct berval **bvPtr);
30
31
32       ber_tag_tber_get_next(Sockbuf *sb, ber_len_t *len, BerElement *ber);
33
34
35       ber_tag_t ber_skip_tag(BerElement *ber, ber_len_t *len);
36
37
38       ber_tag_t ber_peek_tag(BerElement *ber, ber_len_t *len);
39
40
41       ber_tag_t ber_get_int(BerElement *ber, ber_int_t *num);
42
43
44       ber_tag_t ber_get_stringb(BerElement *ber, char *buf,
45            ber_len_t *len);
46
47
48       ber_tag_t ber_get_stringa(BerElement *ber, char **buf);
49
50
51       ber_tag_t ber_get_stringal(BerElement *ber, struct berval **bv);
52
53
54       ber_tag_t ber_get_null(BerElement *ber);
55
56
57       ber_tag_t ber_get_boolean(BerElement *ber, int *boolval);
58
59
60       ber_tag_t ber_get_bitstringa(BerElement *ber, char **buf,
61            ber_len_t *len);
62
63
64       ber_tag_t ber_first_element(BerElement *ber, ber_len_t *len,
65            char **last);
66
67
68       ber_tag_t ber_next_element(BerElement *ber, ber_len_t *len,
69            char *last);
70
71
72       ber_tag_t ber_scanf(BerElement *ber, const char *fmt [, arg...]);
73
74
75       void ber_bvfree(struct berval *bv);
76
77
78       void ber_bvecfree(struct berval **bvec);
79
80

DESCRIPTION

82       These functions provide a subfunction interface to a simplified  imple‐
83       mentation  of  the  Basic  Encoding Rules of ASN.1.  The version of BER
84       these functions support is the one defined for the LDAP protocol.   The
85       encoding  rules  are  the  same as BER, except that  only definite form
86       lengths are used, and bitstrings and octet strings are  always  encoded
87       in  primitive  form.   In  addition,  these  lightweight  BER functions
88       restrict tags and class to fit in a single octet (this means the actual
89       tag must be less than 31). When a "tag"is specified in the descriptions
90       below, it refers to the tag, class, and primitive or constructed bit in
91       the  first octet of the encoding.  This man page describes the decoding
92       functions in the lber library.  See  ber_encode(3LDAP) for  details  on
93       the corresponding encoding functions.
94
95
96       Normally,  the only functions that need be called by an application are
97       ber_get_next() to get the next BER element and  ber_scanf() to  do  the
98       actual  decoding.   In  some cases,  ber_peek_tag() may also need to be
99       called in normal usage. The other  functions  are  provided  for  those
100       applications that need more control than  ber_scanf() provides. In gen‐
101       eral, these functions return the tag of the element decoded, or  −1  if
102       an error occurred.
103
104
105       The   ber_get_next() function is used to read the next BER element from
106       the given Sockbuf, sb.  A Sockbuf consists of the  descriptor  (usually
107       socket,  but  a file descriptor works just as well) from which to read,
108       and a BerElement structure used to maintain a  buffer.   On  the  first
109       call,  the  sb_ber  struct should be zeroed.  It strips off and returns
110       the leading tag byte, strips off and returns the length of  the  entire
111       element  in  len, and sets up ber for subsequent calls to  ber_scanf(),
112       and all to decode the element.
113
114
115       The ber_peek_tag() function returns the tag of the next element  to  be
116       parsed in the BerElement argument. The length of this element is stored
117       in the *lenPtr argument. LBER_DEFAULT is returned if there is  no  fur‐
118       ther  data to be read. The decoding position within the ber argument is
119       unchanged by this call; that is, the fact that ber_peek_tag() has  been
120       called does not affect future use of ber.
121
122
123       The  ber_skip_tag()  function is similar to ber_peek_tag(), except that
124       the state pointer in the BerElement argument is advanced past the first
125       tag  and  length, and is pointed to the value part of the next element.
126       This function should only be used with constructed types and situations
127       when  a  BER  encoding  is  used  as the value of an OCTET STRING.  The
128       length of the value is stored in *lenPtr.
129
130
131       The  ber_scanf() function is used to decode a BER element in  much  the
132       same  way  that   scanf(3C)  works.   It reads from ber, a pointer to a
133       BerElement such as returned by  ber_get_next(),  interprets  the  bytes
134       according to the format string fmt, and stores the results in its addi‐
135       tional arguments.  The format string contains conversion specifications
136       which  are  used  to direct the interpretation of the BER element.  The
137       format string can contain the following characters.
138
139       a    Octet string.  A char ** should be supplied.  Memory is allocated,
140            filled with the contents of the octet string, null-terminated, and
141            returned in the parameter.
142
143
144       s    Octet string.  A char * buffer should be supplied, followed  by  a
145            pointer to an integer initialized to the size of the buffer.  Upon
146            return, the null-terminated octet string is put into  the  buffer,
147            and the integer is set to the actual size of the octet string.
148
149
150       O    Octet  string.  A struct ber_val ** should be supplied, which upon
151            return points to a memory allocated struct berval  containing  the
152            octet  string and its length.   ber_bvfree() can be called to free
153            the allocated memory.
154
155
156       b    Boolean.  A pointer to an integer should be supplied.
157
158
159       i    Integer.  A pointer to an integer should be supplied.
160
161
162       B    Bitstring.  A char ** should be supplied which will point  to  the
163            memory  allocated bits, followed by an unsigned long *, which will
164            point to the length (in bits) of the bitstring returned.
165
166
167       n    Null.  No parameter is required.  The element is simply skipped if
168            it is recognized.
169
170
171       v    Sequence  of  octet strings.  A char *** should be supplied, which
172            upon return points to a memory allocated null-terminated array  of
173            char  *'s  containing the octet strings.   NULL is returned if the
174            sequence is empty.
175
176
177       V    Sequence of octet strings with lengths. A struct berval *** should
178            be supplied, which upon return points to a memory allocated, null-
179            terminated array of struct berval *'s containing the octet strings
180            and  their  lengths.  NULL  is  returned if the sequence is empty.
181            ber_bvecfree() can be called to free the allocated memory.
182
183
184       x    Skip element.  The next element is skipped.
185
186
187       {    Begin sequence.  No parameter is required.  The  initial  sequence
188            tag and length are skipped.
189
190
191       }    End sequence.  No parameter is required and no action is taken.
192
193
194       [    Begin  set.   No  parameter  is required.  The initial set tag and
195            length are skipped.
196
197
198       ]    End set.  No parameter is required and no action is taken.
199
200
201
202       The ber_get_int() function tries to interpret the next  element  as  an
203       integer,  returning  the result in num. The tag of whatever it finds is
204       returned on success, -1 on failure.
205
206
207       The ber_get_stringb() function is used to read an octet string  into  a
208       pre-allocated  buffer.  The  len parameter should be initialized to the
209       size of the buffer, and will contain the length  of  the  octet  string
210       read  upon  return.   The buffer should be big enough to take the octet
211       string value plus a terminating NULL byte.
212
213
214       The ber_get_stringa() function is used to allocate  memory  space  into
215       which an octet string is read.
216
217
218       The  ber_get_stringal()  function is used to allocate memory space into
219       which an octet string and its length  are  read.   It  takes  a  struct
220       berval **, and returns the result in this parameter.
221
222
223       The ber_get_null() function is used to read a NULL element.  It returns
224       the tag of the element it skips over.
225
226
227       The ber_get_boolean() function is used to read a boolean value.  It  is
228       called the same way that ber_get_int() is called.
229
230
231       The ber_get_bitstringa() function is used to read a bitstring value. It
232       takes a char ** which will hold the allocated memory bits, followed  by
233       an  unsigned  long  *,  which will point to the length (in bits) of the
234       bitstring returned.
235
236
237       The ber_first_element() function is used to return the tag  and  length
238       of  the  first  element in a set or sequence. It also returns in last a
239       magic cookie parameter that should be passed  to  subsequent  calls  to
240       ber_next_element(), which returns similar information.
241
242
243       The  ber_alloc_t()  function  constructs and returns BerElement. A null
244       pointer  is returned on error. The options field contains a  bitwise-OR
245       of   options  which are to be used when generating the encoding of this
246       BerElement. One option is defined and must always be supplied:
247
248         #define LBER_USE_DER 0x01
249
250
251
252       When this option is present, lengths will always be encoded in the min‐
253       imum  number  of octets. Note that this option does not cause values of
254       sets and sequences to be rearranged in tag and  byte  order,  so  these
255       functions  are  not  suitable  for  generating DER output as defined in
256       X.509 and X.680
257
258
259       The ber_init function constructs a BerElement and returns a new BerEle‐
260       ment  containing  a  copy  of the data in the bv argument. The ber_init
261       function returns the null pointer on error.
262
263
264       The ber_free() function frees a BerElement which is returned  from  the
265       API calls ber_alloc_t() or ber_init(). Each BerElement must be freed by
266       the caller. The second argument freebuf should always be set  to  1  to
267       ensure  that  the internal buffer used by the BER functions is freed as
268       well as the BerElement container itself.
269
270
271       The ber_bvdup() function returns a copy of a berval. The  bv_val  field
272       in  the  returned  berval  points  to a different area of memory as the
273       bv_val field in the argument berval. The null pointer  is  returned  on
274       error (that is, is out of memory).
275
276
277       The  ber_flatten()  function  allocates a struct  berval whose contents
278       are BER encoding taken from the  ber argument. The bvPtr pointer points
279       to  the  returned  berval, which must be freed using ber_bvfree(). This
280       function returns 0 on success and  −1 on error.
281

EXAMPLES

283       Example 1 Assume the variable ber contains a lightweight  BER  encoding
284       of the following ASN.1 object:
285
286               AlmostASearchRequest := SEQUENCE {
287                   baseObject      DistinguishedName,
288                   scope           ENUMERATED {
289                       baseObject    (0),
290                       singleLevel   (1),
291                       wholeSubtree  (2)
292                   },
293                   derefAliases    ENUMERATED {
294                       neverDerefaliases   (0),
295                       derefInSearching    (1),
296                       derefFindingBaseObj (2),
297                       alwaysDerefAliases  (3N)
298                   },
299                   sizelimit       INTEGER (0 .. 65535),
300                   timelimit       INTEGER (0 .. 65535),
301                   attrsOnly       BOOLEAN,
302                   attributes      SEQUENCE OF AttributeType
303               }
304
305
306       Example 2 The element can be decoded using ber_scanf() as follows.
307
308               int    scope, ali, size, time, attrsonly;
309               char   *dn, **attrs;
310               if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,
311                   &size, &time, &attrsonly, &attrs ) == -1 )
312                       /* error */
313               else
314                       /* success */
315
316

ERRORS

318       If  an  error  occurs during decoding, generally these functions return
319       −1.
320

NOTES

322       The return values for all  of  these  functions  are  declared  in  the
323       <lber.h>  header.   Some  functions  may  allocate memory which must be
324       freed by the calling application.
325

ATTRIBUTES

327       See attributes(5) for a description of the following attributes:
328
329
330
331
332       ┌─────────────────────────────┬─────────────────────────────┐
333       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
334       ├─────────────────────────────┼─────────────────────────────┤
335       │Availability                 │SUNWcsl (32-bit)             │
336       ├─────────────────────────────┼─────────────────────────────┤
337       │                             │SUNWcslx (64-bit)            │
338       ├─────────────────────────────┼─────────────────────────────┤
339       │Interface Stability          │Committed                    │
340       └─────────────────────────────┴─────────────────────────────┘
341