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

   1 .TH LDAP_GET_DN 3 "21 July 2000" "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 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 .SH DESCRIPTION
  35 These routines allow LDAP entry names (Distinguished Names, or DNs)
  36 to be obtained, parsed, converted to a user-friendly form, and tested.
  37 A DN has the form described in
  38 RFC 2253 "Lightweight Directory Access Protocol (v3):
  39 UTF-8 String Representation of Distinguished Names".
  40 .LP
  41 The
  42 .B ldap_get_dn()
  43 routine takes an \fIentry\fP as returned by
  44 .BR ldap_first_entry (3)
  45 or
  46 .BR ldap_next_entry (3)
  47 and returns a copy of
  48 the entry's DN.  Space for the DN will be obtained dynamically
  49 and should be freed by the caller using
  50 .BR ldap_memfree (3).
  51 .LP
  52 The
  53 .B ldap_explode_dn()
  54 routine takes a DN as returned by
  55 .B ldap_get_dn()
  56 and breaks it up into its component parts.  Each part is known as a
  57 Relative Distinguished Name, or RDN.
  58 .B ldap_explode_dn()
  59 returns a
  60 NULL-terminated array, each component of which contains an RDN from the
  61 DN.  The \fInotypes\fP parameter is used to request that only the RDN
  62 values be returned, not their types.  For example, the DN "cn=Bob,
  63 c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
  64 "US", NULL }, depending on whether notypes was 0 or 1, respectively.
  65 The result can be freed by calling
  66 .BR ldap_value_free (3).
  67 .LP
  68 Similarly, the
  69 .B ldap_explode_rdn()
  70 routine takes an RDN as returned by
  71 .B ldap_explode_dn(dn,0)
  72 and breaks it up into its "type=value" component parts (or just "value",
  73 if the \fInotypes\fP parameter is set).  The result can be freed by
  74 calling
  75 .BR ldap_value_free (3).
  76 .LP
  77 .B ldap_dn2ufn()
  78 is used to turn a DN as returned by
  79 .B ldap_get_dn()
  80 into a more user-friendly form, stripping off type names.  See
  81 RFC 1781 "Using the Directory to Achieve User Friendly Naming"
  82 for more details on the UFN format.  The space for the UFN returned
  83 is obtained dynamically and the user is responsible for freeing it
  84 via a call to
  85 .BR ldap_memfree (3).
  86 .SH ERRORS
  87 If an error occurs in
  88 .BR ldap_get_dn() ,
  89 NULL is returned and the
  90 .B ld_errno
  91 field in the \fIld\fP parameter is set to indicate the error.  See
  92 .BR ldap_error (3)
  93 for a description of possible error codes.
  94 .BR ldap_explode_dn() ,
  95 .BR ldap_explode_rdn() ,
  96 and
  97 .B ldap_dn2ufn()
  98 will return NULL with
  99 .BR errno (3)
 100 set appropriately in case of trouble.
 101 .SH NOTES
 102 These routines dyanamically allocate memory that the caller must free.
 103 .SH SEE ALSO
 104 .BR ldap(3),
 105 .BR ldap_error(3),
 106 .BR ldap_first_entry(3),
 107 .BR ldap_memfree(3),
 108 .BR ldap_value_free(3)
 109 .SH ACKNOWLEDGEMENTS
 110 .B      OpenLDAP
 111 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 112 .B      OpenLDAP
 113 is derived from University of Michigan LDAP 3.3 Release.