ldap_get_dn,       ldap_explode_dn,      ldap_explode_rdn,
       ldap_dn2ufn - LDAP DN handling routines


SYNOPSIS

       #include <ldap.h>

       char *ldap_get_dn(ld, entry)
       LDAP *ld;
       LDAPMessage *entry;

       char **ldap_explode_dn(dn, notypes)
       char *dn;
       int notypes;

       char **ldap_explode_rdn(rdn, notypes)
       char *rdn;
       int notypes;

       char *ldap_dn2ufn(dn)
       char *dn;


DESCRIPTION

       These  routines  allow  LDAP  entry  names  (Distinguished
       Names,  or  DNs)  to  be  obtained, parsed, converted to a
       user-friendly  form,  and  tested.   A  DN  has  the  form
       described in RFC 2253 "Lightweight Directory Access Proto­
       col (v3): UTF-8  String  Representation  of  Distinguished
       Names".

       The  ldap_get_dn()  routine  takes an entry as returned by
       ldap_first_entry(3) or ldap_next_entry(3)  and  returns  a
       copy of the entry's DN.  Space for the DN will be obtained
       dynamically and  should  be  freed  by  the  caller  using
       ldap_memfree(3).

       The  ldap_explode_dn()  routine  takes a DN as returned by
       ldap_get_dn() and breaks it up into its  component  parts.
       Each  part  is  known as a Relative Distinguished Name, or
       RDN.  ldap_explode_dn() returns a  NULL-terminated  array,
       each  component of which contains an RDN from the DN.  The
       notypes parameter is used to request  that  only  the  RDN
       values  be returned, not their types.  For example, the DN
       "cn=Bob, c=US" would return as either { "cn=Bob",  "c=US",
       NULL  }  or  {  "Bob",  "US", NULL }, depending on whether
       notypes was 0 or 1, respectively.  The result can be freed
       by calling ldap_value_free(3).

       Similarly,  the ldap_explode_rdn() routine takes an RDN as
       returned by ldap_explode_dn(dn,0) and breaks  it  up  into
       its  "type=value" component parts (or just "value", if the
       notypes parameter is set).  The result  can  be  freed  by
       calling ldap_value_free(3).

       ldap_get_dn() into a more  user-friendly  form,  stripping
       off  type  names.   See  RFC  1781 "Using the Directory to
       Achieve User Friendly Naming" for more details on the  UFN
       format.  The space for the UFN returned is obtained dynam­
       ically and the user is responsible for freeing  it  via  a
       call to ldap_memfree(3).


ERRORS

       If  an error occurs in ldap_get_dn(), NULL is returned and
       the ld_errno field in the ld parameter is set to  indicate
       the  error.  See ldap_error(3) for a description of possi­
       ble error codes.   ldap_explode_dn(),  ldap_explode_rdn(),
       and  ldap_dn2ufn()  will  return  NULL  with  errno(3) set
       appropriately in case of trouble.


NOTES

       These  routines  dyanamically  allocate  memory  that  the
       caller must free.


SEE ALSO

       ldap(3),   ldap_error(3),  ldap_first_entry(3),  ldap_mem­
       free(3), ldap_value_free(3)


ACKNOWLEDGEMENTS

       OpenLDAP is developed and maintained by The OpenLDAP  Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html