1 .TH LDAP_GET_DN 3 "22 July 2001" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2000 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
13 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
16 char **ldap_explode_dn( const char *dn, int notypes )
19 char **ldap_explode_rdn( const char *rdn, int notypes )
22 char *ldap_dn2ufn( const char * dn )
25 char *ldap_dn2dcedn( const char * dn )
28 char *ldap_dcedn2dn( const char * dn )
31 char *ldap_dn2ad_canonical( const char * dn )
34 int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
37 int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
39 These routines allow LDAP entry names (Distinguished Names, or DNs)
40 to be obtained, parsed, converted to a user-friendly form, and tested.
41 A DN has the form described in
42 RFC 2253 "Lightweight Directory Access Protocol (v3):
43 UTF-8 String Representation of Distinguished Names".
47 routine takes an \fIentry\fP as returned by
48 .BR ldap_first_entry (3)
50 .BR ldap_next_entry (3)
52 the entry's DN. Space for the DN will be obtained dynamically
53 and should be freed by the caller using
58 routine takes a DN as returned by
60 and breaks it up into its component parts. Each part is known as a
61 Relative Distinguished Name, or RDN.
64 NULL-terminated array, each component of which contains an RDN from the
65 DN. The \fInotypes\fP parameter is used to request that only the RDN
66 values be returned, not their types. For example, the DN "cn=Bob,
67 c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
68 "US", NULL }, depending on whether notypes was 0 or 1, respectively.
69 The result can be freed by calling
70 .BR ldap_value_free (3).
74 routine takes an RDN as returned by
75 .B ldap_explode_dn(dn,0)
76 and breaks it up into its "type=value" component parts (or just "value",
77 if the \fInotypes\fP parameter is set). Note the value is not
78 unescaped. The result can be freed by calling
79 .BR ldap_value_free (3).
82 is used to turn a DN as returned by
84 into a more user-friendly form, stripping off all type names. See
85 "Using the Directory to Achieve User Friendly Naming" (RFC 1781)
86 for more details on the UFN format. Due to the ambigious nature
87 of the format, it is generally only used for display purposes.
88 The space for the UFN returned is obtained dynamically and the user
89 is responsible for freeing it via a call to
93 is used to turn a DN as returned by
95 into a DCE-style DN, e.g. a string with most-significant to least
96 significant rdns separated by slashes ('/'); rdn components
97 are separated by commas (',').
98 Only printable chars (e.g. LDAPv2 printable string) are allowed,
99 at least in this implementation.
101 performs the opposite operation.
102 .B ldap_dn2ad_canonical()
103 turns a DN into a AD canonical name, which is basically a DCE dn
104 with attribute types omitted.
105 The trailing domain, if present, is turned in a DNS-like domain.
106 The space for the returned value is obtained dynamically and the user
107 is responsible for freeing it via a call to
108 .BR ldap_memfree (3).
111 parses a string representation of a distinguished name contained in
118 structures, arranged in
127 typedef struct ldap_ava {
129 struct berval *la_value;
133 typedef LDAPAVA** LDAPRDN;
134 typedef LDAPRDN** LDAPDN;
138 The attribute types and the attribute values are not normalized.
145 the latter meaning that the value is BER/DER encoded and thus must
146 be represented as, quoting from RFC 2253, " ... an
147 octothorpe character ('#' ASCII 35) followed by the hexadecimal
148 representation of each of the bytes of the BER encoding of the X.500
157 LDAP_DN_FORMAT_LDAPV3
158 LDAP_DN_FORMAT_LDAPV2
162 which defines what DN syntax is expected (according to RFC 2253,
163 RFC 1779 and DCE, respectively).
164 The format can be \fIOR\fPed to the flags
168 LDAP_DN_P_NO_SPACE_AFTER_RDN
173 The latter is a shortcut for all the previous limitations.
175 .B LDAP_DN_P_NO_SPACES
176 does not allow extra spaces in the dn; the default is to silently
177 eliminate spaces around AVA separators ('='), RDN component separators
178 ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators
179 (',' LDAPv3/LDAPv2 or '/' for DCE).
181 .B LDAP_DN_P_NO_SPACE_AFTER_RDN
182 does not allow a single space after RDN separators.
185 performs the inverse operation, yielding in
187 a string representation of
189 It allows the same values for
197 LDAP_DN_FORMAT_AD_CANONICAL
200 for user-friendly naming (RFC 1781) and AD canonical.
202 If an error occurs in
204 NULL is returned and the
206 field in the \fIld\fP parameter is set to indicate the error. See
208 for a description of possible error codes.
209 .BR ldap_explode_dn() ,
210 .BR ldap_explode_rdn() ,
215 .B ldap_dn2ad_canonical()
216 will return NULL with
218 set appropriately in case of trouble.
220 These routines dynamically allocate memory that the caller must free.
224 .BR ldap_first_entry(3),
226 .BR ldap_value_free(3)
229 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
231 is derived from University of Michigan LDAP 3.3 Release.