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