LDAP_GET_DN

NAME

LIBRARY

SYNOPSIS

#include <ldap.h>

char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )

int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )

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

The ldap_get_dn() routine takes an entry as returned by ldap_first_entry(3) or ldap_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 using ldap_memfree(3).

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, defined as:

typedef struct ldap_ava {
    char *la_attr;
    struct berval *la_value;
    unsigned la_flags;
} LDAPAVA;

typedef LDAPAVA** LDAPRDN;
typedef LDAPRDN** LDAPDN;

        LDAP_DN_FORMAT_LDAPV3
        LDAP_DN_FORMAT_LDAPV2
        LDAP_DN_FORMAT_DCE

        LDAP_DN_P_NO_SPACES
        LDAP_DN_P_NO_SPACE_AFTER_RDN
        ...
        LDAP_DN_PEDANTIC

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

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).  

ERRORS

NOTES

SEE ALSO

ACKNOWLEDGEMENTS