Update lber-encode/decode man pages

Add ber_get_enum() for symmetry

diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3
index bf2d4525fba38e3515f01a2bacf6ac82bf9c6b30..70b260f2a33f3a0d8f082c1e598901c465abc25d 100644 (file)
--- a/doc/man/man3/lber-decode.3
+++ b/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

diff --git a/doc/man/man3/lber-decode.3.links b/doc/man/man3/lber-decode.3.links
index 8d43e71e66bc9850cb39aa730ae725426cfb3709..3ec93287f94f2c1269375ee90ba1fe0792fd7b71 100644 (file)
--- a/doc/man/man3/lber-decode.3.links
+++ b/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

diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3
index f2fab9b612f4b879b1ff6e673daceac7d9ffff6c..9d5fbb980dc7b3179383570e369ab9c49faad3d7 100644 (file)
--- a/doc/man/man3/lber-encode.3
+++ b/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

diff --git a/doc/man/man3/lber-encode.3.links b/doc/man/man3/lber-encode.3.links
index e1fef9a76411987c44420d43cc729350b4f2d68c..54cd0e9669a48d69ccaf78f79af4418443e19bba 100644 (file)
--- a/doc/man/man3/lber-encode.3.links
+++ b/doc/man/man3/lber-encode.3.links
@@ -1,10 +1,11 @@
-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

diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3
index a501251abc3b0dcfd9c27f0c74617e79e7801ceb..ca7ee336272afd74cdcaa7fac72e0770eb71f7a2 100644 (file)
--- a/doc/man/man3/ldap.3
+++ b/doc/man/man3/ldap.3
@@ -1,4 +1,4 @@
-.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.

diff --git a/include/lber.h b/include/lber.h
index 8315bacb9dd6b0a4392c2c61691415331e0e753b..515b45b19b929fc82c0205f4866cbe5424460b51 100644 (file)
--- a/include/lber.h
+++ b/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,

diff --git a/libraries/liblber/decode.c b/libraries/liblber/decode.c
index e6f5387261853860a316ab289bb5bc0ef967ccf7..a97e7bd602f57c10ffb9fc12fe71ebf20caaeffa 100644 (file)
--- a/libraries/liblber/decode.c
+++ b/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,

diff --git a/libraries/liblber/nt_err.c b/libraries/liblber/nt_err.c
index d5280ac4d2df7c8d3162115e9e85e5cbfd00447c..45de02c8be38ae5361d3019b9f97d88e480ac5a2 100644 (file)
--- a/libraries/liblber/nt_err.c
+++ b/libraries/liblber/nt_err.c
@@ -1,6 +1,6 @@
 /* $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"