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

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