git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_get_dn.3

   1 .TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 .LP
  12 .ft B
  13 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
  14 .LP
  15 .ft B
  16 int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
  17 .LP
  18 .ft B
  19 int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
  20 .LP
  21 .ft B
  22 char **ldap_explode_dn( const char *dn, int notypes )
  23 .LP
  24 .ft B
  25 char **ldap_explode_rdn( const char *rdn, int notypes )
  26 .LP
  27 .ft B
  28 char *ldap_dn2ufn( const char * dn )
  29 .LP
  30 .ft B
  31 char *ldap_dn2dcedn( const char * dn )
  32 .LP
  33 .ft B
  34 char *ldap_dcedn2dn( const char * dn )
  35 .LP
  36 .ft B
  37 char *ldap_dn2ad_canonical( const char * dn )
  38 .SH DESCRIPTION
  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".
  44 .LP
  45 The
  46 .B ldap_get_dn()
  47 routine takes an \fIentry\fP as returned by
  48 .BR ldap_first_entry (3)
  49 or
  50 .BR ldap_next_entry (3)
  51 and returns a copy of
  52 the entry's DN.  Space for the DN will be obtained dynamically
  53 and should be freed by the caller using
  54 .BR ldap_memfree (3).
  55 .LP
  56 .B ldap_str2dn()
  57 parses a string representation of a distinguished name contained in
  58 .B str
  59 into its components,
  60 which are stored in
  61 .B dn
  62 as
  63 .B ldap_ava
  64 structures, arranged in
  65 .B LDAPAVA,
  66 .B LDAPRDN,
  67 and
  68 .B LDAPDN
  69 terms, defined as:
  70 .nf
  71 .ft B
  72
  73 typedef struct ldap_ava {
  74     char *la_attr;
  75     struct berval *la_value;
  76     unsigned la_flags;
  77 } LDAPAVA;
  78
  79 typedef LDAPAVA** LDAPRDN;
  80 typedef LDAPRDN** LDAPDN;
  81
  82 .ft
  83 .fi
  84 The attribute types and the attribute values are not normalized.
  85 The
  86 .B la_flags
  87 can be either
  88 .B LDAP_AVA_STRING
  89 or
  90 .B LDAP_AVA_BINARY,
  91 the latter meaning that the value is BER/DER encoded and thus must
  92 be represented as, quoting from RFC 2253, " ... an
  93 octothorpe character ('#' ASCII 35) followed by the hexadecimal
  94 representation of each of the bytes of the BER encoding of the X.500
  95 AttributeValue."
  96 The
  97 .B flags
  98 parameter to
  99 .B ldap_str2dn()
 100 can be
 101 .LP
 102 .nf
 103         LDAP_DN_FORMAT_LDAPV3
 104         LDAP_DN_FORMAT_LDAPV2
 105         LDAP_DN_FORMAT_DCE
 106
 107 .fi
 108 which defines what DN syntax is expected (according to RFC 2253,
 109 RFC 1779 and DCE, respectively).
 110 The format can be \fIOR\fPed to the flags
 111 .LP
 112 .nf
 113         LDAP_DN_P_NO_SPACES
 114         LDAP_DN_P_NO_SPACE_AFTER_RDN
 115         ...
 116         LDAP_DN_PEDANTIC
 117
 118 .fi
 119 The latter is a shortcut for all the previous limitations.
 120 .LP
 121 .B LDAP_DN_P_NO_SPACES
 122 does not allow extra spaces in the dn; the default is to silently
 123 eliminate spaces around AVA separators ('='), RDN component separators
 124 ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators
 125 (',' LDAPv3/LDAPv2 or '/' for DCE).
 126 .LP
 127 .B LDAP_DN_P_NO_SPACE_AFTER_RDN
 128 does not allow a single space after RDN separators.
 129 .LP
 130 .B ldap_dn2str()
 131 performs the inverse operation, yielding in
 132 .B str
 133 a string representation of
 134 .B dn.
 135 It allows the same values for
 136 .B flags
 137 as
 138 .B ldap_str2dn(),
 139 plus
 140 .LP
 141 .nf
 142         LDAP_DN_FORMAT_UFN
 143         LDAP_DN_FORMAT_AD_CANONICAL
 144
 145 .fi
 146 for user-friendly naming (RFC 1781) and AD canonical.
 147 .LP
 148 The following routines are viewed as deprecated in favor of
 149 .B ldap_str2dn()
 150 and
 151 .BR ldap_dn2str().
 152 They are provided to support legacy applications.
 153 .LP
 154 The
 155 .B ldap_explode_dn()
 156 routine takes a DN as returned by
 157 .B ldap_get_dn()
 158 and breaks it up into its component parts.  Each part is known as a
 159 Relative Distinguished Name, or RDN.
 160 .B ldap_explode_dn()
 161 returns a
 162 NULL-terminated array, each component of which contains an RDN from the
 163 DN.  The \fInotypes\fP parameter is used to request that only the RDN
 164 values be returned, not their types.  For example, the DN "cn=Bob,
 165 c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
 166 "US", NULL }, depending on whether notypes was 0 or 1, respectively.
 167 Assertion values in RDN strings may included escaped characters.
 168 The result can be freed by calling
 169 .BR ldap_value_free (3).
 170 .LP
 171 Similarly, the
 172 .B ldap_explode_rdn()
 173 routine takes an RDN as returned by
 174 .B ldap_explode_dn(dn,0)
 175 and breaks it up into its "type=value" component parts (or just "value",
 176 if the \fInotypes\fP parameter is set).  Note the value is not
 177 unescaped.  The result can be freed by calling
 178 .BR ldap_value_free (3).
 179 .LP
 180 .B ldap_dn2ufn()
 181 is used to turn a DN as returned by
 182 .BR ldap_get_dn (3)
 183 into a more user-friendly form, stripping off all type names.  See
 184 "Using the Directory to Achieve User Friendly Naming" (RFC 1781)
 185 for more details on the UFN format.  Due to the ambigious nature
 186 of the format, it is generally only used for display purposes.
 187 The space for the UFN returned is obtained dynamically and the user
 188 is responsible for freeing it via a call to
 189 .BR ldap_memfree (3).
 190 .LP
 191 .B ldap_dn2dcedn()
 192 is used to turn a DN as returned by
 193 .BR ldap_get_dn (3)
 194 into a DCE-style DN, e.g. a string with most-significant to least
 195 significant rdns separated by slashes ('/'); rdn components
 196 are separated by commas (',').
 197 Only printable chars (e.g. LDAPv2 printable string) are allowed,
 198 at least in this implementation.
 199 .B ldap_dcedn2dn()
 200 performs the opposite operation.
 201 .B ldap_dn2ad_canonical()
 202 turns a DN into a AD canonical name, which is basically a DCE dn
 203 with attribute types omitted.
 204 The trailing domain, if present, is turned in a DNS-like domain.
 205 The space for the returned value is obtained dynamically and the user
 206 is responsible for freeing it via a call to
 207 .BR ldap_memfree (3).
 208 .SH ERRORS
 209 If an error occurs in
 210 .BR ldap_get_dn() ,
 211 NULL is returned and the
 212 .B ld_errno
 213 field in the \fIld\fP parameter is set to indicate the error.  See
 214 .BR ldap_error (3)
 215 for a description of possible error codes.
 216 .BR ldap_explode_dn() ,
 217 .BR ldap_explode_rdn() ,
 218 .B ldap_dn2ufn(),
 219 .B ldap_dn2dcedn(),
 220 .B ldap_dcedn2dn(),
 221 and
 222 .B ldap_dn2ad_canonical()
 223 will return NULL with
 224 .BR errno (3)
 225 set appropriately in case of trouble.
 226 .SH NOTES
 227 These routines dynamically allocate memory that the caller must free.
 228 .SH SEE ALSO
 229 .BR ldap (3),
 230 .BR ldap_error (3),
 231 .BR ldap_first_entry (3),
 232 .BR ldap_memfree (3),
 233 .BR ldap_value_free (3)
 234 .SH ACKNOWLEDGEMENTS
 235 .B      OpenLDAP
 236 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 237 .B      OpenLDAP
 238 is derived from University of Michigan LDAP 3.3 Release.