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-2011 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 LIBRARY
   8 OpenLDAP LDAP (libldap, \-lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <ldap.h>
  13 .LP
  14 .ft B
  15 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
  16 .LP
  17 .ft B
  18 int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags )
  19 .LP
  20 .ft B
  21 void ldap_dnfree( LDAPDN dn )
  22 .LP
  23 .ft B
  24 int ldap_dn2str( LDAPDN dn, char **str, unsigned flags )
  25 .LP
  26 .ft B
  27 char **ldap_explode_dn( const char *dn, int notypes )
  28 .LP
  29 .ft B
  30 char **ldap_explode_rdn( const char *rdn, int notypes )
  31 .LP
  32 .ft B
  33 char *ldap_dn2ufn( const char * dn )
  34 .LP
  35 .ft B
  36 char *ldap_dn2dcedn( const char * dn )
  37 .LP
  38 .ft B
  39 char *ldap_dcedn2dn( const char * dn )
  40 .LP
  41 .ft B
  42 char *ldap_dn2ad_canonical( const char * dn )
  43 .SH DESCRIPTION
  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".
  49 .LP
  50 The
  51 .B ldap_get_dn()
  52 routine takes an \fIentry\fP as returned by
  53 .BR ldap_first_entry (3)
  54 or
  55 .BR ldap_next_entry (3)
  56 and returns a copy of
  57 the entry's DN.  Space for the DN will be obtained dynamically
  58 and should be freed by the caller using
  59 .BR ldap_memfree (3).
  60 .LP
  61 .B ldap_str2dn()
  62 parses a string representation of a distinguished name contained in
  63 .B str
  64 into its components,
  65 which are stored in
  66 .B dn
  67 as
  68 .B ldap_ava
  69 structures, arranged in
  70 .B LDAPAVA,
  71 .B LDAPRDN,
  72 and
  73 .B LDAPDN
  74 terms.  Space for
  75 .B dn
  76 will be obtained dynamically and should be freed by the caller using
  77 .BR ldap_dnfree (3).
  78 The
  79 .B LDAPDN
  80 is defined as:
  81 .nf
  82 .ft B
  83
  84 typedef struct ldap_ava {
  85     char *la_attr;
  86     struct berval *la_value;
  87     unsigned la_flags;
  88 } LDAPAVA;
  89
  90 typedef LDAPAVA** LDAPRDN;
  91 typedef LDAPRDN* LDAPDN;
  92
  93 .ft
  94 .fi
  95 The attribute types and the attribute values are not normalized.
  96 The
  97 .B la_flags
  98 can be either
  99 .B LDAP_AVA_STRING
 100 or
 101 .B LDAP_AVA_BINARY,
 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
 106 AttributeValue."
 107 The
 108 .B flags
 109 parameter to
 110 .B ldap_str2dn()
 111 can be
 112 .LP
 113 .nf
 114         LDAP_DN_FORMAT_LDAPV3
 115         LDAP_DN_FORMAT_LDAPV2
 116         LDAP_DN_FORMAT_DCE
 117
 118 .fi
 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
 122 .LP
 123 .nf
 124         LDAP_DN_P_NO_SPACES
 125         LDAP_DN_P_NO_SPACE_AFTER_RDN
 126         ...
 127         LDAP_DN_PEDANTIC
 128
 129 .fi
 130 The latter is a shortcut for all the previous limitations.
 131 .LP
 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).
 137 .LP
 138 .B LDAP_DN_P_NO_SPACE_AFTER_RDN
 139 does not allow a single space after RDN separators.
 140 .LP
 141 .B ldap_dn2str()
 142 performs the inverse operation, yielding in
 143 .B str
 144 a string representation of
 145 .B dn.
 146 It allows the same values for
 147 .B flags
 148 as
 149 .B ldap_str2dn(),
 150 plus
 151 .LP
 152 .nf
 153         LDAP_DN_FORMAT_UFN
 154         LDAP_DN_FORMAT_AD_CANONICAL
 155
 156 .fi
 157 for user-friendly naming (RFC 1781) and AD canonical.
 158 .LP
 159 The following routines are viewed as deprecated in favor of
 160 .B ldap_str2dn()
 161 and
 162 .BR ldap_dn2str().
 163 They are provided to support legacy applications.
 164 .LP
 165 The
 166 .B ldap_explode_dn()
 167 routine takes a DN as returned by
 168 .B ldap_get_dn()
 169 and breaks it up into its component parts.  Each part is known as a
 170 Relative Distinguished Name, or RDN.
 171 .B ldap_explode_dn()
 172 returns a
 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).
 181 .LP
 182 Similarly, the
 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).
 190 .LP
 191 .B ldap_dn2ufn()
 192 is used to turn a DN as returned by
 193 .BR ldap_get_dn (3)
 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).
 201 .LP
 202 .B ldap_dn2dcedn()
 203 is used to turn a DN as returned by
 204 .BR ldap_get_dn (3)
 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.
 210 .B ldap_dcedn2dn()
 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).
 219 .SH ERRORS
 220 If an error occurs in
 221 .BR ldap_get_dn() ,
 222 NULL is returned and the
 223 .B ld_errno
 224 field in the \fIld\fP parameter is set to indicate the error.  See
 225 .BR ldap_error (3)
 226 for a description of possible error codes.
 227 .BR ldap_explode_dn() ,
 228 .BR ldap_explode_rdn() ,
 229 .B ldap_dn2ufn(),
 230 .B ldap_dn2dcedn(),
 231 .B ldap_dcedn2dn(),
 232 and
 233 .B ldap_dn2ad_canonical()
 234 will return NULL with
 235 .BR errno (3)
 236 set appropriately in case of trouble.
 237 .SH NOTES
 238 These routines dynamically allocate memory that the caller must free.
 239 .SH SEE ALSO
 240 .BR ldap (3),
 241 .BR ldap_error (3),
 242 .BR ldap_first_entry (3),
 243 .BR ldap_memfree (3),
 244 .BR ldap_value_free (3)
 245 .SH ACKNOWLEDGEMENTS
 246 .so ../Project