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

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