1 .TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines
8 OpenLDAP LDAP (libldap, \-lldap)
15 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
18 int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags )
21 void ldap_dnfree( LDAPDN dn )
24 int ldap_dn2str( LDAPDN dn, char **str, unsigned flags )
27 char **ldap_explode_dn( const char *dn, int notypes )
30 char **ldap_explode_rdn( const char *rdn, int notypes )
33 char *ldap_dn2ufn( const char * dn )
36 char *ldap_dn2dcedn( const char * dn )
39 char *ldap_dcedn2dn( const char * dn )
42 char *ldap_dn2ad_canonical( const char * dn )
44 These routines allow LDAP entry names (Distinguished Names, or DNs)
45 to be obtained, parsed, converted to a user-friendly form, and tested.
46 A DN has the form described in
47 RFC 4414 "Lightweight Directory Access Protocol (LDAP):
48 String Representation of Distinguished Names".
52 routine takes an \fIentry\fP as returned by
53 .BR ldap_first_entry (3)
55 .BR ldap_next_entry (3)
57 the entry's DN. Space for the DN will be obtained dynamically
58 and should be freed by the caller using
62 parses a string representation of a distinguished name contained in
69 structures, arranged in
76 will be obtained dynamically and should be freed by the caller using
84 typedef struct ldap_ava {
86 struct berval *la_value;
90 typedef LDAPAVA** LDAPRDN;
91 typedef LDAPRDN* LDAPDN;
95 The attribute types and the attribute values are not normalized.
102 the latter meaning that the value is BER/DER encoded and thus must
103 be represented as, quoting from RFC 4514, " ... an
104 octothorpe character ('#' ASCII 35) followed by the hexadecimal
105 representation of each of the bytes of the BER encoding of the X.500
114 LDAP_DN_FORMAT_LDAPV3
115 LDAP_DN_FORMAT_LDAPV2
119 which defines what DN syntax is expected (according to RFC 4514,
120 RFC 1779 and DCE, respectively).
121 The format can be \fIOR\fPed to the flags
125 LDAP_DN_P_NO_SPACE_AFTER_RDN
130 The latter is a shortcut for all the previous limitations.
132 .B LDAP_DN_P_NO_SPACES
133 does not allow extra spaces in the dn; the default is to silently
134 eliminate spaces around AVA separators ('='), RDN component separators
135 ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators
136 (',' LDAPv3/LDAPv2 or '/' for DCE).
138 .B LDAP_DN_P_NO_SPACE_AFTER_RDN
139 does not allow a single space after RDN separators.
142 performs the inverse operation, yielding in
144 a string representation of
146 It allows the same values for
154 LDAP_DN_FORMAT_AD_CANONICAL
157 for user-friendly naming (RFC 1781) and AD canonical.
159 The following routines are viewed as deprecated in favor of
163 They are provided to support legacy applications.
167 routine takes a DN as returned by
169 and breaks it up into its component parts. Each part is known as a
170 Relative Distinguished Name, or RDN.
173 NULL-terminated array, each component of which contains an RDN from the
174 DN. The \fInotypes\fP parameter is used to request that only the RDN
175 values be returned, not their types. For example, the DN "cn=Bob,
176 c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
177 "US", NULL }, depending on whether notypes was 0 or 1, respectively.
178 Assertion values in RDN strings may included escaped characters.
179 The result can be freed by calling
180 .BR ldap_value_free (3).
183 .B ldap_explode_rdn()
184 routine takes an RDN as returned by
185 .B ldap_explode_dn(dn,0)
186 and breaks it up into its "type=value" component parts (or just "value",
187 if the \fInotypes\fP parameter is set). Note the value is not
188 unescaped. The result can be freed by calling
189 .BR ldap_value_free (3).
192 is used to turn a DN as returned by
194 into a more user-friendly form, stripping off all type names. See
195 "Using the Directory to Achieve User Friendly Naming" (RFC 1781)
196 for more details on the UFN format. Due to the ambiguous nature
197 of the format, it is generally only used for display purposes.
198 The space for the UFN returned is obtained dynamically and the user
199 is responsible for freeing it via a call to
200 .BR ldap_memfree (3).
203 is used to turn a DN as returned by
205 into a DCE-style DN, e.g. a string with most-significant to least
206 significant rdns separated by slashes ('/'); rdn components
207 are separated by commas (',').
208 Only printable chars (e.g. LDAPv2 printable string) are allowed,
209 at least in this implementation.
211 performs the opposite operation.
212 .B ldap_dn2ad_canonical()
213 turns a DN into a AD canonical name, which is basically a DCE dn
214 with attribute types omitted.
215 The trailing domain, if present, is turned in a DNS-like domain.
216 The space for the returned value is obtained dynamically and the user
217 is responsible for freeing it via a call to
218 .BR ldap_memfree (3).
220 If an error occurs in
222 NULL is returned and the
224 field in the \fIld\fP parameter is set to indicate the error. See
226 for a description of possible error codes.
227 .BR ldap_explode_dn() ,
228 .BR ldap_explode_rdn() ,
233 .B ldap_dn2ad_canonical()
234 will return NULL with
236 set appropriately in case of trouble.
238 These routines dynamically allocate memory that the caller must free.
242 .BR ldap_first_entry (3),
243 .BR ldap_memfree (3),
244 .BR ldap_value_free (3)