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 4414 "Lightweight Directory Access Protocol (LDAP):
String Representation of Distinguished Names".

ldap_str2dn() parses a string representation of a distinguished name contained in
str into its components,
which are stored in
dn as
ldap_ava structures, arranged in
LDAPAVA,LDAPRDN, and
LDAPDN terms. Space for
dn will be obtained dynamically and should be freed by the caller using
ldap_dnfree(3).
The
LDAPDN is defined as:

The attribute types and the attribute values are not normalized.
The
la_flags can be either
LDAP_AVA_STRING or
LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must
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."
The
flags parameter to
ldap_str2dn() can be

LDAP_DN_FORMAT_LDAPV3
LDAP_DN_FORMAT_LDAPV2
LDAP_DN_FORMAT_DCE

which defines what DN syntax is expected (according to RFC 4514,
RFC 1779 and DCE, respectively).
The format can be ORed to the flags

LDAP_DN_P_NO_SPACES
LDAP_DN_P_NO AFTER_RDN
...
LDAP_DN_PEDANTIC

The latter is a shortcut for all the previous limitations.

LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently
eliminate spaces around AVA separators (=), RDN component separators
(+ for LDAPv3/LDAPv2 or , for DCE) and RDN separators
(, LDAPv3/LDAPv2 or / for DCE).

LDAP_DN_P_NO AFTER_RDN does not allow a single space after RDN separators.

ldap_dn2str() performs the inverse operation, yielding in
str a string representation of
dn. It allows the same values for
flags as
ldap_str2dn(), plus

LDAP_DN_FORMAT_UFN
LDAP_DN_FORMAT_AD_CANONICAL

for user-friendly naming (RFC 1781) and AD canonical.

The following routines are viewed as deprecated in favor of
ldap_str2dn() and
ldap_dn2str(). They are provided to support legacy applications.

The
ldap_explode_dn() routine takes a DN as returned by
ldap_get_dn() and breaks it up into its component parts. Each part is known as a
Relative Distinguished Name, or RDN.
ldap_explode_dn() returns a
NULL-terminated array, each component of which contains an RDN from the
DN. The notypes 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
ldap_value_free(3).

Similarly, the
ldap_explode_rdn() routine takes an RDN as returned by
ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value",
if the notypes parameter is set). Note the value is not
unescaped. The result can be freed by calling
ldap_value_free(3).

ldap_dn2ufn() is used to turn a DN as returned by
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
ldap_memfree(3).

ldap_dn2dcedn() is used to turn a DN as returned by
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.
ldap_dcedn2dn() performs the opposite operation.
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
ldap_memfree(3).

If an error occurs in
ldap_get_dn(), NULL is returned and the
ld_errno field in the ld parameter is set to indicate the error. See
ldap_error(3)
for a description of possible error codes.
ldap_explode_dn(),
ldap_explode_rdn(),
ldap_dn2ufn(),ldap_dn2dcedn(),ldap_dcedn2dn(), and
ldap_dn2ad_canonical() will return NULL with
errno(3)
set appropriately in case of trouble.