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