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

   1 .TH LDAP_GET_DN 3 "22 July 2001" "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 char **ldap_explode_dn( const char *dn, int notypes )
  17 .LP
  18 .ft B
  19 char **ldap_explode_rdn( const char *rdn, int notypes )
  20 .LP
  21 .ft B
  22 char *ldap_dn2ufn( const char * dn )
  23 .LP
  24 .ft B
  25 char *ldap_dn2dcedn( const char * dn )
  26 .LP
  27 .ft B
  28 char *ldap_dcedn2dn( const char * dn )
  29 .LP
  30 .ft B
  31 char *ldap_dn2ad_canonical( const char * dn )
  32 .LP
  33 .ft B
  34 int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
  35 .LP
  36 .ft B
  37 int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
  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 The
  57 .B ldap_explode_dn()
  58 routine takes a DN as returned by
  59 .B ldap_get_dn()
  60 and breaks it up into its component parts.  Each part is known as a
  61 Relative Distinguished Name, or RDN.
  62 .B ldap_explode_dn()
  63 returns a
  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).
  71 .LP
  72 Similarly, the
  73 .B ldap_explode_rdn()
  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).
  80 .LP
  81 .B ldap_dn2ufn()
  82 is used to turn a DN as returned by
  83 .BR ldap_get_dn (3)
  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
  90 .BR ldap_memfree (3).
  91 .LP
  92 .B ldap_dn2dcedn()
  93 is used to turn a DN as returned by
  94 .BR ldap_get_dn (3)
  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.
 100 .B ldap_dcedn2dn()
 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).
 109 .LP
 110 .B ldap_str2dn()
 111 parses a string representation of a distinguished name contained in
 112 .B str
 113 into its components,
 114 which are stored in
 115 .B dn
 116 as
 117 .B ldap_ava
 118 structures, arranged in
 119 .B LDAPAVA,
 120 .B LDAPRDN,
 121 and
 122 .B LDAPDN
 123 terms, defined as:
 124 .nf
 125 .ft B
 126
 127 typedef struct ldap_ava {
 128     char *la_attr;
 129     struct berval *la_value;
 130     unsigned la_flags;
 131 } LDAPAVA;
 132
 133 typedef LDAPAVA** LDAPRDN;
 134 typedef LDAPRDN** LDAPDN;
 135
 136 .ft
 137 .fi
 138 The attribute types and the attribute values are not normalized.
 139 The
 140 .B la_flags
 141 can be either
 142 .B LDAP_AVA_STRING
 143 or
 144 .B LDAP_AVA_BINARY,
 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
 149 AttributeValue."
 150 The
 151 .B flags
 152 parameter to
 153 .B ldap_str2dn()
 154 can be
 155 .LP
 156 .nf
 157         LDAP_DN_FORMAT_LDAPV3
 158         LDAP_DN_FORMAT_LDAPV2
 159         LDAP_DN_FORMAT_DCE
 160
 161 .fi
 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
 165 .LP
 166 .nf
 167         LDAP_DN_P_NO_SPACES
 168         LDAP_DN_P_NO_SPACE_AFTER_RDN
 169         ...
 170         LDAP_DN_PEDANTIC
 171
 172 .fi
 173 The latter is a shortcut for all the previous limitations.
 174 .LP
 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).
 180 .LP
 181 .B LDAP_DN_P_NO_SPACE_AFTER_RDN
 182 does not allow a single space after RDN separators.
 183 .LP
 184 .B ldap_dn2str()
 185 performs the inverse operation, yielding in
 186 .B str
 187 a string representation of
 188 .B dn.
 189 It allows the same values for
 190 .B flags
 191 as
 192 .B ldap_str2dn(),
 193 plus
 194 .LP
 195 .nf
 196         LDAP_DN_FORMAT_UFN
 197         LDAP_DN_FORMAT_AD_CANONICAL
 198
 199 .fi
 200 for user-friendly naming (RFC 1781) and AD canonical.
 201 .SH ERRORS
 202 If an error occurs in
 203 .BR ldap_get_dn() ,
 204 NULL is returned and the
 205 .B ld_errno
 206 field in the \fIld\fP parameter is set to indicate the error.  See
 207 .BR ldap_error (3)
 208 for a description of possible error codes.
 209 .BR ldap_explode_dn() ,
 210 .BR ldap_explode_rdn() ,
 211 .B ldap_dn2ufn(),
 212 .B ldap_dn2dcedn(),
 213 .B ldap_dcedn2dn(),
 214 and
 215 .B ldap_dn2ad_canonical()
 216 will return NULL with
 217 .BR errno (3)
 218 set appropriately in case of trouble.
 219 .SH NOTES
 220 These routines dynamically allocate memory that the caller must free.
 221 .SH SEE ALSO
 222 .BR ldap (3),
 223 .BR ldap_error (3),
 224 .BR ldap_first_entry (3),
 225 .BR ldap_memfree (3),
 226 .BR ldap_value_free (3)
 227 .SH ACKNOWLEDGEMENTS
 228 .B      OpenLDAP
 229 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 230 .B      OpenLDAP
 231 is derived from University of Michigan LDAP 3.3 Release.