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

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