external/bsd/openldap/man/ldap_get_dn.3

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