--- name: "ldap_get_dn" section: "3" platform: "linux" package: "libldap" version: "2.7.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux", "macos"] url: "https://new.carta.tech/ldap_get_dn" --- # ldap\_get\_dn(3) LDAP DN handling routines ## NAME ldap\_get\_dn, ldap\_explode\_dn, ldap\_explode\_rdn, ldap\_dn2ufn - LDAP DN handling routines ## LIBRARY OpenLDAP LDAP (libldap, -lldap) ## SYNOPSIS ``` #include ``` **char \*ldap\_get\_dn( LDAP \*ld, LDAPMessage \*entry )** **int ldap\_str2dn( const char \*str, LDAPDN \*dn, unsigned flags )** **void ldap\_dnfree( LDAPDN dn )** **int ldap\_dn2str( LDAPDN dn, char \*\*str, unsigned flags )** **char \*\*ldap\_explode\_dn( const char \*dn, int notypes )** **char \*\*ldap\_explode\_rdn( const char \*rdn, int notypes )** **char \*ldap\_dn2ufn( const char \* dn )** **char \*ldap\_dn2dcedn( const char \* dn )** **char \*ldap\_dcedn2dn( const char \* dn )** **char \*ldap\_dn2ad\_canonical( const char \* dn )** ## 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 4414 "Lightweight Directory Access Protocol (LDAP):** **String Representation of Distinguished Names".** **The** **ldap\_get\_dn()** **routine takes an** *entry* **as returned by** [**ldap\_first\_entry**(3)](/ldap_first_entry/3.md) **or** [**ldap\_next\_entry**(3)](/ldap_next_entry/3.md) **and returns a copy of** **the entry's DN. Space for the DN will be obtained dynamically** **and should be freed by the caller using** [**ldap\_memfree**(3)](/ldap_memfree/3.md). **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)](/ldap_dnfree/3.md). **The** **LDAPDN** **is defined as:** ``` typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; ``` **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** *OR***ed to the flags** ``` LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_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\_SPACE\_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)](/ldap_value_free/3.md). **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_value_free/3.md). **ldap\_dn2ufn()** **is used to turn a DN as returned by** [**ldap\_get\_dn**(3)](/ldap_get_dn/3.md) **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_memfree/3.md). **ldap\_dn2dcedn()** **is used to turn a DN as returned by** [**ldap\_get\_dn**(3)](/ldap_get_dn/3.md) **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)](/ldap_memfree/3.md). ## ERRORS **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)](/ldap_error/3.md) **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)](/errno/3.md) **set appropriately in case of trouble.** ## NOTES **These routines dynamically allocate memory that the caller must free.** ## SEE ALSO [**ldap**(3)](/ldap/3.md), [**ldap\_error**(3)](/ldap_error/3.md), [**ldap\_first\_entry**(3)](/ldap_first_entry/3.md), [**ldap\_memfree**(3)](/ldap_memfree/3.md), [**ldap\_value\_free**(3)](/ldap_value_free/3.md) ## ACKNOWLEDGEMENTS **OpenLDAP Software** **is developed and maintained by The OpenLDAP Project \.** **OpenLDAP Software** **is derived from the University of Michigan LDAP 3.3 Release.**