Make it clear that ldap_explode_dn() and friends are deprecated.

diff --git a/doc/man/man3/ldap_get_dn.3 b/doc/man/man3/ldap_get_dn.3
index ac4979270db41cb704ea4c921b9021b877e6d336..ac7cab89b42e878d21251455340f00d1d90dea5a 100644 (file)
--- a/doc/man/man3/ldap_get_dn.3
+++ b/doc/man/man3/ldap_get_dn.3
@@ -13,6 +13,12 @@ ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling
 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
 .LP
 .ft B
+int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
+.LP
+.ft B
+int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
+.LP
+.ft B
 char **ldap_explode_dn( const char *dn, int notypes )
 .LP
 .ft B
@@ -29,12 +35,6 @@ char *ldap_dcedn2dn( const char * dn )
 .LP
 .ft B
 char *ldap_dn2ad_canonical( const char * dn )
-.LP
-.ft B
-int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
-.LP
-.ft B
-int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
 .SH DESCRIPTION
 These routines allow LDAP entry names (Distinguished Names, or DNs)
 to be obtained, parsed, converted to a user-friendly form, and tested.
@@ -53,60 +53,6 @@ the entry's DN.  Space for the DN will be obtained dynamically
 and should be freed by the caller using 
 .BR ldap_memfree (3).
 .LP
-The
-.B ldap_explode_dn()
-routine takes a DN as returned by
-.B ldap_get_dn()
-and breaks it up into its component parts.  Each part is known as a
-Relative Distinguished Name, or RDN.
-.B ldap_explode_dn()
-returns a
-NULL-terminated array, each component of which contains an RDN from the
-DN.  The \fInotypes\fP parameter is used to request that only the RDN
-values be returned, not their types.  For example, the DN "cn=Bob,
-c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
-"US", NULL }, depending on whether notypes was 0 or 1, respectively.
-The result can be freed by calling
-.BR ldap_value_free (3).
-.LP
-Similarly, the
-.B ldap_explode_rdn()
-routine takes an RDN as returned by
-.B ldap_explode_dn(dn,0)
-and breaks it up into its "type=value" component parts (or just "value",
-if the \fInotypes\fP parameter is set).  Note the value is not
-unescaped.  The result can be freed by calling
-.BR ldap_value_free (3).
-.LP
-.B ldap_dn2ufn()
-is used to turn a DN as returned by
-.BR ldap_get_dn (3)
-into a more user-friendly form, stripping off all type names.  See
-"Using the Directory to Achieve User Friendly Naming" (RFC 1781)
-for more details on the UFN format.  Due to the ambigious nature
-of the format, it is generally only used for display purposes.
-The space for the UFN returned is obtained dynamically and the user
-is responsible for freeing it via a call to
-.BR ldap_memfree (3).
-.LP
-.B ldap_dn2dcedn()
-is used to turn a DN as returned by
-.BR ldap_get_dn (3)
-into a DCE-style DN, e.g. a string with most-significant to least 
-significant rdns separated by slashes ('/'); rdn components
-are separated by commas (',').
-Only printable chars (e.g. LDAPv2 printable string) are allowed,
-at least in this implementation.
-.B ldap_dcedn2dn()
-performs the opposite operation.
-.B ldap_dn2ad_canonical()
-turns a DN into a AD canonical name, which is basically a DCE dn
-with attribute types omitted.
-The trailing domain, if present, is turned in a DNS-like domain.
-The space for the returned value is obtained dynamically and the user
-is responsible for freeing it via a call to
-.BR ldap_memfree (3).
-.LP
 .B ldap_str2dn()
 parses a string representation of a distinguished name contained in
 .B str
@@ -198,6 +144,67 @@ plus
 
 .fi
 for user-friendly naming (RFC 1781) and AD canonical.
+.LP
+The following routines are viewed as deprecated in favor of
+.B ldap_str2dn()
+and
+.BR ldap_dn2str().
+They are provided to support legacy applications.
+.LP
+The
+.B ldap_explode_dn()
+routine takes a DN as returned by
+.B ldap_get_dn()
+and breaks it up into its component parts.  Each part is known as a
+Relative Distinguished Name, or RDN.
+.B ldap_explode_dn()
+returns a
+NULL-terminated array, each component of which contains an RDN from the
+DN.  The \fInotypes\fP parameter is used to request that only the RDN
+values be returned, not their types.  For example, the DN "cn=Bob,
+c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
+"US", NULL }, depending on whether notypes was 0 or 1, respectively.
+Assertion values in RDN strings may included escaped characters.
+The result can be freed by calling
+.BR ldap_value_free (3).
+.LP
+Similarly, the
+.B ldap_explode_rdn()
+routine takes an RDN as returned by
+.B ldap_explode_dn(dn,0)
+and breaks it up into its "type=value" component parts (or just "value",
+if the \fInotypes\fP parameter is set).  Note the value is not
+unescaped.  The result can be freed by calling
+.BR ldap_value_free (3).
+.LP
+.B ldap_dn2ufn()
+is used to turn a DN as returned by
+.BR ldap_get_dn (3)
+into a more user-friendly form, stripping off all type names.  See
+"Using the Directory to Achieve User Friendly Naming" (RFC 1781)
+for more details on the UFN format.  Due to the ambigious nature
+of the format, it is generally only used for display purposes.
+The space for the UFN returned is obtained dynamically and the user
+is responsible for freeing it via a call to
+.BR ldap_memfree (3).
+.LP
+.B ldap_dn2dcedn()
+is used to turn a DN as returned by
+.BR ldap_get_dn (3)
+into a DCE-style DN, e.g. a string with most-significant to least 
+significant rdns separated by slashes ('/'); rdn components
+are separated by commas (',').
+Only printable chars (e.g. LDAPv2 printable string) are allowed,
+at least in this implementation.
+.B ldap_dcedn2dn()
+performs the opposite operation.
+.B ldap_dn2ad_canonical()
+turns a DN into a AD canonical name, which is basically a DCE dn
+with attribute types omitted.
+The trailing domain, if present, is turned in a DNS-like domain.
+The space for the returned value is obtained dynamically and the user
+is responsible for freeing it via a call to
+.BR ldap_memfree (3).
 .SH ERRORS
 If an error occurs in
 .BR ldap_get_dn() ,