HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |ERRORS |NOTES |SEE ALSO |ACKNOWLEDGEMENTS |COLOPHON | |
LDAP_GET_DN(3) Library Functions ManualLDAP_GET_DN(3)ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn - LDAP DN handling routines
OpenLDAP LDAP (libldap, -lldap)
#include <ldap.h>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 )
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". Theldap_get_dn()routine takes anentry as returned byldap_first_entry(3) orldap_next_entry(3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller usingldap_memfree(3).ldap_str2dn()parses a string representation of a distinguished name contained instrinto its components, which are stored indn asldap_avastructures, arranged inLDAPAVA, LDAPRDN,andLDAPDN terms. Space fordnwill be obtained dynamically and should be freed by the caller usingldap_dnfree(3). TheLDAPDNis 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. Thela_flagscan be eitherLDAP_AVA_STRINGorLDAP_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." Theflagsparameter toldap_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 beORed 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_SPACESdoes 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_RDNdoes not allow a single space after RDN separators.ldap_dn2str()performs the inverse operation, yielding instra string representation ofdn.It allows the same values forflags asldap_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 ofldap_str2dn()andldap_dn2str().They are provided to support legacy applications. Theldap_explode_dn()routine takes a DN as returned byldap_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. Thenotypes 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 callingldap_value_free(3). Similarly, theldap_explode_rdn()routine takes an RDN as returned byldap_explode_dn(dn,0)and breaks it up into its "type=value" component parts (or just "value", if thenotypes parameter is set). Note the value is not unescaped. The result can be freed by callingldap_value_free(3).ldap_dn2ufn()is used to turn a DN as returned byldap_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 toldap_memfree(3).ldap_dn2dcedn()is used to turn a DN as returned byldap_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 toldap_memfree(3).If an error occurs inldap_get_dn(), NULL is returned and theld_errnofield in theld parameter is set to indicate the error. Seeldap_error(3) for a description of possible error codes.ldap_explode_dn(),ldap_explode_rdn(),ldap_dn2ufn(),ldap_dn2dcedn(), ldap_dcedn2dn(),andldap_dn2ad_canonical()will return NULL witherrno(3) set appropriately in case of trouble.
These routines dynamically allocate memory that the caller must free.
ldap(3),ldap_error(3),ldap_first_entry(3),ldap_memfree(3),ldap_value_free(3)
OpenLDAP Softwareis developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.OpenLDAP Softwareis derived from the University of Michigan LDAP 3.3 Release.
This page is part of theOpenLDAP (an open source implementation of the Lightweight Directory Access Protocol) project. Information about the project can be found at ⟨http://www.openldap.org/⟩. If you have a bug report for this manual page, see ⟨http://www.openldap.org/its/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.openldap.org/openldap/openldap.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-05.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgOpenLDAP LDVERSION RELEASEDATELDAP_GET_DN(3)Pages that refer to this page:ldap_first_entry(3), ldap_get_dn(3), ldap_sync(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |