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