git.sur5r.net Git - openldap/blob - doc/man/man3/lber-encode.3

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