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

   1 .TH LDAP_GET_DN 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2000 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_is_dns_dn, ldap_explode_dns \- 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(ld, entry)
  14 .ft
  15 LDAP *ld;
  16 LDAPMessage *entry;
  17 .LP
  18 .ft B
  19 char **ldap_explode_dn(dn, notypes)
  20 .ft
  21 char *dn;
  22 int notypes;
  23 .LP
  24 .ft B
  25 char **ldap_explode_rdn(rdn, notypes)
  26 .ft
  27 char *rdn;
  28 int notypes;
  29 .LP
  30 .ft B
  31 char *ldap_dn2ufn(dn)
  32 .ft
  33 char *dn;
  34 .LP
  35 .ft B
  36 int ldap_is_dns_dn(dn)
  37 .ft
  38 char *dn;
  39 .LP
  40 .ft B
  41 char **ldap_explode_dns(dn)
  42 .ft
  43 char *dn;
  44 .SH DESCRIPTION
  45 These routines allow LDAP entry names (Distinguished Names, or DNs)
  46 to be obtained, parsed, converted to a user-friendly form, and tested.
  47 A DN has the form described in RFC 1779 "A String Representation of
  48 Distinguished Names", unless it is an experimental DNS-style DN
  49 which takes the form of an RFC 822 mail address.
  50 .LP
  51 The
  52 .B ldap_get_dn()
  53 routine takes an \fIentry\fP as returned by
  54 .BR ldap_first_entry (3)
  55 or
  56 .BR ldap_next_entry (3)
  57 and returns a copy of
  58 the entry's DN.  Space for the DN will be obtained dynamically
  59 and should be freed by the caller using
  60 .BR ldap_memfree (3).
  61 .LP
  62 The
  63 .B ldap_explode_dn()
  64 routine takes a DN as returned by
  65 .B ldap_get_dn()
  66 and breaks it up into its component parts.  Each part is known as a
  67 Relative Distinguished Name, or RDN.
  68 .B ldap_explode_dn()
  69 returns a
  70 NULL-terminated array, each component of which contains an RDN from the
  71 DN.  The \fInotypes\fP parameter is used to request that only the RDN
  72 values be returned, not their types.  For example, the DN "cn=Bob,
  73 c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
  74 "US", NULL }, depending on whether notypes was 0 or 1, respectively.
  75 The result can be freed by calling
  76 .BR ldap_value_free (3).
  77 .LP
  78 Similarly, the
  79 .B ldap_explode_rdn()
  80 routine takes an RDN as returned by
  81 .B ldap_explode_dn(dn,0)
  82 and breaks it up into its "type=value" component parts (or just "value",
  83 if the \fInotypes\fP parameter is set).  The result can be freed by
  84 calling
  85 .BR ldap_value_free (3).
  86 .LP
  87 .B ldap_dn2ufn()
  88 is used to turn a DN as returned by
  89 .B ldap_get_dn()
  90 into a more user-friendly form, stripping off type names.  See
  91 RFC 1781 "Using the Directory to Achieve User Friendly Naming"
  92 for more details on the UFN format.  The space for the UFN returned
  93 is obtained dynamically and the user is responsible for freeing it
  94 via a call to
  95 .BR ldap_memfree (3).
  96 .LP
  97 .B ldap_is_dns_dn()
  98 returns non-zero if the dn string is an experimental
  99 DNS-style DN (generally in the form of an RFC 822 e-mail address).  It
 100 returns zero if the dn appears to be an RFC 1779 format DN.
 101 .LP
 102 .B ldap_explode_dns()
 103 takes a DNS-style DN and breaks it up into its
 104 component parts.
 105 .B ldap_explode_dns()
 106 returns a NULL-terminated array.
 107 For example, the DN "mcs.umich.edu" will return { "mcs", "umich", "edu",
 108 NULL }.  The result can be freed by calling
 109 .BR ldap_value_free (3).
 110 .SH ERRORS
 111 If an error occurs in
 112 .BR ldap_get_dn() ,
 113 NULL is returned and the
 114 .B ld_errno
 115 field in the \fIld\fP parameter is set to indicate the error.  See
 116 .BR ldap_error (3)
 117 for a description of possible error codes.
 118 .BR ldap_explode_dn() ,
 119 .BR ldap_explode_rdn() ,
 120 .B ldap_explode_dns()
 121 and
 122 .B ldap_dn2ufn()
 123 will return NULL with
 124 .BR errno (3)
 125 set appropriately in case of trouble.
 126 .SH NOTES
 127 These routines dyanamically allocate memory that the caller must free.
 128 .SH SEE ALSO
 129 .BR ldap(3),
 130 .BR ldap_error(3),
 131 .BR ldap_first_entry(3),
 132 .BR ldap_memfree(3),
 133 .BR ldap_value_free(3)
 134 .SH ACKNOWLEDGEMENTS
 135 .B      OpenLDAP
 136 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 137 .B      OpenLDAP
 138 is derived from University of Michigan LDAP 3.3 Release.