From cbaf9f66493ec56bb7121c702cf5113bcfcf128b Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Mon, 17 Jun 2002 22:45:34 +0000 Subject: [PATCH] Make it clear that ldap_explode_dn() and friends are deprecated. --- doc/man/man3/ldap_get_dn.3 | 127 +++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 60 deletions(-) diff --git a/doc/man/man3/ldap_get_dn.3 b/doc/man/man3/ldap_get_dn.3 index ac4979270d..ac7cab89b4 100644 --- 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() , -- 2.39.5