Update lber-encode/decode man pages

Add ber_get_enum() for symmetry

doc/man/man3/lber-decode.3

@@ -3,7 +3,7 @@
 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ber_get_next, ber_skiptag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_stringb, ber_get_stringa, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- LBER simplified Basic Encoding Rules library routines for decoding
+ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- LBER simplified Basic Encoding Rules library routines for decoding
 .SH SYNOPSIS
 .nf
 .ft B
@@ -46,7 +46,15 @@ ber_tag_t ber_scanf(
 .LP
 .nf
 .ft B
-ber_tag_t ber_get_int(ber, num)
+ber_tag_t ber_get_int(
+	BerElement \(**ber,
+	ber_int_t \(**num);
+.ft
+.fi
+.LP
+.nf
+.ft B
+ber_tag_t ber_get_enum(
 	BerElement \(**ber,
 	ber_int_t \(**num);
 .ft
@@ -166,7 +174,7 @@ characters.
 Octet string.  A char ** should be supplied.  Memory is allocated,
 filled with the contents of the octet string, null-terminated, and
 returned in the parameter.
-The caller should free the returned ber_val using ber_memfree();
+The caller should free the returned ber_val using ber_memfree().
 .TP
 .SM s
 Octet string.  A char * buffer should be supplied, followed by a pointer
@@ -178,11 +186,19 @@ set to the actual size of the octet string.
 Octet string.  A struct ber_val ** should be supplied, which upon return
 points to a dynamically allocated struct berval containing the octet string
 and its length.
-The caller should free the returned structure using ber_bvfree();
+The caller should free the returned structure using ber_bvfree().
+.TP
+.SM o
+Octet string.  A struct ber_val * should be supplied, which upon return
+points containing the dynamically allocated octet string and its length.
+The caller should free the returned octet string using ber_memfree().
 .TP
 .SM b
 Boolean.  A pointer to a ber_int_t should be supplied.
 .TP
+.SM e
+Enumeration.  A pointer to a ber_int_t should be supplied.
+.TP
 .SM i
 Integer.  A pointer to a ber_int_t should be supplied.
 .TP
@@ -200,6 +216,8 @@ it is recognized.
 Sequence of octet strings.  A char *** should be supplied, which upon
 return points to a dynamically allocated null-terminated array of char *'s
 containing the octet strings.  NULL is returned if the sequence is empty.
+The caller should free the returned array and octet strings using
+ber_memvfree().
 .TP
 .SM V
 Sequence of octet strings with lengths.
@@ -208,7 +226,16 @@ return points to a dynamically allocated null-terminated array of
 struct berval *'s
 containing the octet strings and their lengths.
 NULL is returned if the sequence is empty.  
-The caller should free the returned structures using ber_bvecfree();
+The caller should free the returned structures using ber_bvecfree().
+.TP
+.SM l
+Length of the next element.  A pointer to a ber_len_t should be supplied.
+.TP
+.SM t
+Tag of the next element.  A pointer to a ber_tag_t should be supplied.
+.TP
+.SM T
+Skip element and return its tag.  A pointer to a ber_tag_t should be supplied.
 .TP
 .SM x
 Skip element.  The next element is skipped.
@@ -240,24 +267,26 @@ string value plus a terminating NULL byte.
 .LP
 The ber_get_stringa() routine is used to dynamically allocate space into
 which an octet string is read.
-The caller should free the returned string using ber_memfree();
+The caller should free the returned string using ber_memfree().
 .LP
 The ber_get_stringal() routine is used to dynamically allocate space
 into which an octet string and its length are read.  It takes a
 struct berval **, and returns the result in this parameter.
-The caller should free the returned structure using ber_bvfree();
+The caller should free the returned structure using ber_bvfree().
 .LP
 The ber_get_null() routine is used to read a NULL element.  It returns
 the tag of the element it skips over.
 .LP
-The ber_get_boolean() routine is used to read a boolean value.  It is called
-the same way that ber_get_int() is called.
+The ber_get_boolean() routine is used to read a boolean value.
+It is called the same way that ber_get_int() is called.
+.LP
+The ber_get_enum() routine is used to read a enumeration value.
+It is called the same way that ber_get_int() is called.
 .LP
 The ber_get_bitstringa() routine is used to read a bitstring value.  It
 takes a char ** which will hold the dynamically allocated bits, followed by an
-unsigned long *, which will point to the length (in bits) of the
-bitstring returned.
-The caller should free the returned string using ber_memfree();
+ber_len_t *, which will point to the length (in bits) of the bitstring returned.
+The caller should free the returned string using ber_memfree().
 .LP
 The ber_first_element() routine is used to return the tag and length
 of the first element in a set or sequence.  It also returns in \fIcookie\fP
@@ -291,12 +320,12 @@ the following ASN.1 object:
 The element can be decoded using ber_scanf() as follows.
 .LP
 .nf
-      ber_int_t    scope, ali, size, time, attrsonly;
+      ber_int_t    scope, deref, size, time, attrsonly;
       char   *dn, **attrs;
       ber_tag_t tag;
 
-      tag = ber_scanf( ber, "{aiiiib{v}}",
-          &dn, &scope, &ali,
+      tag = ber_scanf( ber, "{aeeiib{v}}",
+          &dn, &scope, &deref,
           &size, &time, &attrsonly, &attrs );
 
       if( tag == LBER_ERROR ) {
@@ -304,6 +333,9 @@ The element can be decoded using ber_scanf() as follows.
       } else {
               /* success */
       }
+
+      ber_memfree( dn );
+      ber_memvfree( attrs );
 .fi
 .SH ERRORS
 If an error occurs during decoding, generally these routines return
@@ -322,8 +354,8 @@ which must be freed by the caller using supplied deallocation routines.
 .BR ldap-sync (3)
 .BR ldap-async (3)
 .LP
-Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
-Protocol", OSI-DS-26, April 1992.
+Yeong, W., Howes, T., and Hardcastle-Kille, S.,
+"Lightweight Directory Access Protocol", OSI-DS-26, April 1992.
 .LP
 Information Processing - Open Systems Interconnection - Model and Notation -
 Service Definition - Specification of Basic Encoding Rules for Abstract

doc/man/man3/lber-decode.3.links

@@ -6,6 +6,7 @@ ber_get_int.3
 ber_get_stringa.3
 ber_get_stringb.3
 ber_get_null.3
+ber_get_enum.3
 ber_get_boolean.3
 ber_get_bitstring.3
 ber_first_element.3

doc/man/man3/lber-encode.3

@@ -3,7 +3,7 @@
 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-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
+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
 .SH SYNOPSIS
 .nf
 .ft B
@@ -45,6 +45,15 @@ int ber_put_int(
 .LP
 .nf
 .ft B
+int ber_put_enum(
+	BerElement *ber,
+	ber_int_t num,
+	ber_tag_t tag);
+.ft
+.fi
+.LP
+.nf
+.ft B
 int ber_put_ostring(
 	BerElement *ber,
 	const char \(**str,
@@ -140,7 +149,8 @@ applications that need more control than ber_printf() provides.  In
 general, these routines return the length of the element encoded, or
 -1 if an error occurred.
 .LP
-The ber_alloc_t() routine is used to allocate a new BER element.  The
+The ber_alloc_t() routine is used to allocate a new BER element.  It
+should be called with an argument of LBER_USE_DER.  The
 ber_flush() routine is used to actually write the element to a socket
 (or file) descriptor, once it has been fully encoded (using ber_printf()
 and friends).  The \fIsb\fP structure contains the descriptor and a
@@ -162,6 +172,10 @@ The format string can contain the following characters:
 Boolean.  An ber_int_t parameter should be supplied.  A boolean element
 is output.
 .TP
+.SM e
+Enumeration.  An ber_int_t parameter should be supplied.  An
+enumeration element is output.
+.TP
 .SM i
 Integer.  An ber_int_t parameter should be supplied.  An integer element
 is output.
@@ -178,6 +192,10 @@ Null.  No parameter is required.  A null element is output.
 Octet string.  A char * is supplied, followed by the length of the
 string pointed to.  An octet string element is output.
 .TP
+.SM O
+Octet string.  A struct berval * is supplied.
+An octet string element is output.
+.TP
 .SM s
 Octet string.  A null-terminated string is supplied.  An octet string
 element is output, not including the trailing NULL octet.
@@ -191,6 +209,11 @@ Several octet strings.  A null-terminated array of char *'s is
 supplied.  Note that a construct like '{v}' is required to get
 an actual SEQUENCE OF octet strings.
 .TP
+.SM V
+Several octet strings.  A null-terminated array of struct berval *'s
+is supplied.  Note that a construct like '{V}' is required to get
+an actual SEQUENCE OF octet strings.
+.TP
 .SM {
 Begin sequence.  No parameter is required.
 .TP
@@ -207,6 +230,9 @@ End set.  No parameter is required.
 The ber_put_int() routine writes the integer element \fInum\fP to
 the BER element \fIber\fP.
 .LP
+The ber_put_enum() routine writes the enumberation element
+\fInum\fP to the BER element \fIber\fP.
+.LP
 The ber_put_boolean() routine writes the boolean value given by
 \fIbool\fP to the BER element.
 .LP
@@ -263,13 +289,15 @@ can be achieved like so:
       int rc;
       ber_int_t    scope, ali, size, time, attrsonly;
       char   *dn, **attrs;
+      BerElement *ber;
 
       /* ... fill in values ... */
+
       ber = ber_alloc_t( LBER_USE_DER );
 
       if ( ber == NULL ) {
 		/* error */
-     }
+      }
 
       rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
           size, time, attrsonly, attrs );
@@ -294,8 +322,8 @@ The return values for all of these functions are declared in the
 .BR ldap-sync (3)
 .BR ldap-parse (3)
 .LP
-Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
-Protocol", OSI-DS-26, April 1992.
+Yeong, W., Howes, T., and Hardcastle-Kille, S.,
+"Lightweight Directory Access Protocol", OSI-DS-26, April 1992.
 .LP
 Information Processing - Open Systems Interconnection - Model and Notation -
 Service Definition - Specification of Basic Encoding Rules for Abstract

doc/man/man3/lber-encode.3.links

-ber_alloc.3
+ber_alloc_t.3
 ber_flush.3
 ber_printf.3
 ber_put_int.3
 ber_put_ostring.3
 ber_put_string.3
 ber_put_null.3
+ber_put_enum.3
 ber_start_set.3
 ber_put_seq.3
 ber_put_set.3

doc/man/man3/ldap.3

-.TH LDAP 3 "10 November 1998" "OpenLDAP LDVERSION"
+.TH LDAP 3 "13 May 2000" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
@@ -16,8 +16,6 @@ The Lightweight Directory Access Protocol provides TCP/IP access to
 the X.500 Directory or to a stand-alone LDAP server.
 The OpenLDAP LDAP package includes a stand-alone server in
 .BR slapd (8),
-an LDAP to X.500 gateway in
-.BR ldapd (8),
 various LDAP clients, and an LDAP client library used to provide
 programmatic access to the LDAP protocol. This man page gives an
 overview of the LDAP library routines.

include/lber.h

@@ -200,6 +200,11 @@ ber_get_int LDAP_P((
 	BerElement *ber,
 	ber_int_t *num ));
 
+LIBLBER_F( ber_tag_t )
+ber_get_enum LDAP_P((
+	BerElement *ber,
+	ber_int_t *num ));
+
 LIBLBER_F( ber_tag_t )
 ber_get_stringb LDAP_P((
 	BerElement *ber,

libraries/liblber/decode.c

@@ -228,6 +228,14 @@ ber_get_int(
 		return( tag );
 }
 
+ber_tag_t
+ber_get_enum(
+	BerElement *ber,
+	ber_int_t *num )
+{
+	ber_get_int( ber, num );
+}
+
 ber_tag_t
 ber_get_stringb(
 	BerElement *ber,

libraries/liblber/nt_err.c

 /* $OpenLDAP$ */
 /*
- * Copyright 1998-1999 The OpenLDAP Foundation, All Rights Reserved.
+ * Copyright 1998-2000 The OpenLDAP Foundation, All Rights Reserved.
  * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
  */
 #include "portable.h"