1LDAP_GET_DN(3) Library Functions Manual LDAP_GET_DN(3)
2
6 ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn - LDAP DN
7 handling routines
8
10 OpenLDAP LDAP (libldap, -lldap)
11
13 #include <ldap.h>
14 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
16 int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
18 int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
20 char **ldap_explode_dn( const char *dn, int notypes )
22 char **ldap_explode_rdn( const char *rdn, int notypes )
24 char *ldap_dn2ufn( const char * dn )
26 char *ldap_dn2dcedn( const char * dn )
28 char *ldap_dcedn2dn( const char * dn )
30 char *ldap_dn2ad_canonical( const char * dn )
32
34 These routines allow LDAP entry names (Distinguished Names, or DNs) to
35 be obtained, parsed, converted to a user-friendly form, and tested. A
36 DN has the form described in RFC 2253 "Lightweight Directory Access
37 Protocol (v3): UTF-8 String Representation of Distinguished Names".
38 The ldap_get_dn() routine takes an entry as returned by
40 ldap_first_entry(3) or ldap_next_entry(3) and returns a copy of the
41 entry's DN. Space for the DN will be obtained dynamically and should
42 be freed by the caller using ldap_memfree(3).
43 ldap_str2dn() parses a string representation of a distinguished name
45 contained in str into its components, which are stored in dn as
46 ldap_ava structures, arranged in LDAPAVA, LDAPRDN, and LDAPDN terms,
47 defined as:
48 typedef struct ldap_ava {
50 char *la_attr;
51 struct berval *la_value;
52 unsigned la_flags;
53 } LDAPAVA;
54 typedef LDAPAVA** LDAPRDN;
56 typedef LDAPRDN** LDAPDN;
57 The attribute types and the attribute values are not normalized. The
59 la_flags can be either LDAP_AVA_STRING or LDAP_AVA_BINARY, the latter
60 meaning that the value is BER/DER encoded and thus must be represented
61 as, quoting from RFC 2253, " ... an octothorpe character ('#' ASCII 35)
62 followed by the hexadecimal representation of each of the bytes of the
63 BER encoding of the X.500 AttributeValue." The flags parameter to
64 ldap_str2dn() can be
65 LDAP_DN_FORMAT_LDAPV3
67 LDAP_DN_FORMAT_LDAPV2
68 LDAP_DN_FORMAT_DCE
69 which defines what DN syntax is expected (according to RFC 2253, RFC
71 1779 and DCE, respectively). The format can be ORed to the flags
72 LDAP_DN_P_NO_SPACES
74 LDAP_DN_P_NO_SPACE_AFTER_RDN
75 ...
76 LDAP_DN_PEDANTIC
77 The latter is a shortcut for all the previous limitations.
79 LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default
81 is to silently eliminate spaces around AVA separators ('='), RDN compo‐
82 nent separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separa‐
83 tors (',' LDAPv3/LDAPv2 or '/' for DCE).
84 LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN
86 separators.
87 ldap_dn2str() performs the inverse operation, yielding in str a string
89 representation of dn. It allows the same values for flags as
90 ldap_str2dn(), plus
91 LDAP_DN_FORMAT_UFN
93 LDAP_DN_FORMAT_AD_CANONICAL
94 for user-friendly naming (RFC 1781) and AD canonical.
96 The following routines are viewed as deprecated in favor of
98 ldap_str2dn() and ldap_dn2str(). They are provided to support legacy
99 applications.
100 The ldap_explode_dn() routine takes a DN as returned by ldap_get_dn()
102 and breaks it up into its component parts. Each part is known as a
103 Relative Distinguished Name, or RDN. ldap_explode_dn() returns a NULL-
104 terminated array, each component of which contains an RDN from the DN.
105 The notypes parameter is used to request that only the RDN values be
106 returned, not their types. For example, the DN "cn=Bob, c=US" would
107 return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL },
108 depending on whether notypes was 0 or 1, respectively. Assertion val‐
109 ues in RDN strings may included escaped characters. The result can be
110 freed by calling ldap_value_free(3).
111 Similarly, the ldap_explode_rdn() routine takes an RDN as returned by
113 ldap_explode_dn(dn,0) and breaks it up into its "type=value" component
114 parts (or just "value", if the notypes parameter is set). Note the
115 value is not unescaped. The result can be freed by calling
116 ldap_value_free(3).
117 ldap_dn2ufn() is used to turn a DN as returned by ldap_get_dn(3) into a
119 more user-friendly form, stripping off all type names. See "Using the
120 Directory to Achieve User Friendly Naming" (RFC 1781) for more details
121 on the UFN format. Due to the ambiguous nature of the format, it is
122 generally only used for display purposes. The space for the UFN
123 returned is obtained dynamically and the user is responsible for free‐
124 ing it via a call to ldap_memfree(3).
125 ldap_dn2dcedn() is used to turn a DN as returned by ldap_get_dn(3) into
127 a DCE-style DN, e.g. a string with most-significant to least signifi‐
128 cant rdns separated by slashes ('/'); rdn components are separated by
129 commas (','). Only printable chars (e.g. LDAPv2 printable string) are
130 allowed, at least in this implementation. ldap_dcedn2dn() performs the
131 opposite operation. ldap_dn2ad_canonical() turns a DN into a AD canon‐
132 ical name, which is basically a DCE dn with attribute types omitted.
133 The trailing domain, if present, is turned in a DNS-like domain. The
134 space for the returned value is obtained dynamically and the user is
135 responsible for freeing it via a call to ldap_memfree(3).
136
138 If an error occurs in ldap_get_dn(), NULL is returned and the ld_errno
139 field in the ld parameter is set to indicate the error. See
140 ldap_error(3) for a description of possible error codes.
141 ldap_explode_dn(), ldap_explode_rdn(), ldap_dn2ufn(), ldap_dn2dcedn(),
142 ldap_dcedn2dn(), and ldap_dn2ad_canonical() will return NULL with
143 errno(3) set appropriately in case of trouble.
144
146 These routines dynamically allocate memory that the caller must free.
147
149 ldap(3), ldap_error(3), ldap_first_entry(3), ldap_memfree(3),
150 ldap_value_free(3)
151
153 OpenLDAP is developed and maintained by The OpenLDAP Project
154 (http://www.openldap.org/). OpenLDAP is derived from University of
155 Michigan LDAP 3.3 Release.
156OpenLDAP 2.3.34 2007/2/16 LDAP_GET_DN(3)