ldap_explode_dn

LDAP_GET_DN(3)                                                  LDAP_GET_DN(3)



NAME
       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
       Protocol (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_dn2ufn()  is used to turn a DN as returned by 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 dynamically 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   possible   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_memfree(3),
       ldap_value_free(3)

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



OpenLDAP 2.0.27-Release          21 July 2000                   LDAP_GET_DN(3)