-.TH LDAP_GET_DN 3 "22 July 2001" "OpenLDAP LDVERSION"
+.TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2012 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.SH NAME
ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines
+.SH LIBRARY
+OpenLDAP LDAP (libldap, \-lldap)
.SH SYNOPSIS
.nf
.ft B
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
.LP
.ft B
+int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags )
+.LP
+.ft B
+void ldap_dnfree( LDAPDN dn )
+.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
.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.
A DN has the form described in
-RFC 2253 "Lightweight Directory Access Protocol (v3):
-UTF-8 String Representation of Distinguished Names".
+RFC 4414 "Lightweight Directory Access Protocol (LDAP):
+String Representation of Distinguished Names".
.LP
The
.B ldap_get_dn()
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
.B LDAPRDN,
and
.B LDAPDN
-terms, defined as:
+terms. Space for
+.B dn
+will be obtained dynamically and should be freed by the caller using
+.BR ldap_dnfree (3).
+The
+.B LDAPDN
+is defined as:
.nf
.ft B
} LDAPAVA;
typedef LDAPAVA** LDAPRDN;
-typedef LDAPRDN** LDAPDN;
+typedef LDAPRDN* LDAPDN;
.ft
.fi
or
.B LDAP_AVA_BINARY,
the latter meaning that the value is BER/DER encoded and thus must
-be represented as, quoting from RFC 2253, " ... an
+be represented as, quoting from RFC 4514, " ... an
octothorpe character ('#' ASCII 35) followed by the hexadecimal
representation of each of the bytes of the BER encoding of the X.500
AttributeValue."
LDAP_DN_FORMAT_DCE
.fi
-which defines what DN syntax is expected (according to RFC 2253,
+which defines what DN syntax is expected (according to RFC 4514,
RFC 1779 and DCE, respectively).
The format can be \fIOR\fPed to the flags
.LP
.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 ambiguous 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() ,
.SH NOTES
These routines dynamically allocate memory that the caller must free.
.SH SEE ALSO
-.BR ldap(3),
-.BR ldap_error(3),
-.BR ldap_first_entry(3),
-.BR ldap_memfree(3),
-.BR ldap_value_free(3)
+.BR ldap (3),
+.BR ldap_error (3),
+.BR ldap_first_entry (3),
+.BR ldap_memfree (3),
+.BR ldap_value_free (3)
.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+.so ../Project
projects / openldap / blobdiff