.TH LDAP_GET_DN 3 "21 July 2000" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines
.SH SYNOPSIS
.nf
.ft B
#include <ldap.h>
.LP
.ft B
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
.LP
.ft B
char **ldap_explode_dn( const char *dn, int notypes )
.LP
.ft B
char **ldap_explode_rdn( const char *rdn, int notypes )
.LP
.ft B
char *ldap_dn2ufn( const char * dn )
.SH 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".
.LP
The
.B ldap_get_dn()
routine takes an \fIentry\fP as returned by
.BR ldap_first_entry (3)
or
.BR 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 
.BR ldap_memfree (3).
.LP
The
.B ldap_explode_dn()
routine takes a DN as returned by
.B ldap_get_dn()
and breaks it up into its component parts.  Each part is known as a
Relative Distinguished Name, or RDN.
.B ldap_explode_dn()
returns a
NULL-terminated array, each component of which contains an RDN from the
DN.  The \fInotypes\fP 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
.BR ldap_value_free (3).
.LP
Similarly, the
.B ldap_explode_rdn()
routine takes an RDN as returned by
.B ldap_explode_dn(dn,0)
and breaks it up into its "type=value" component parts (or just "value",
if the \fInotypes\fP parameter is set).  Note the value is not
unescaped.  The result can be freed by calling
.BR ldap_value_free (3).
.LP
.B ldap_dn2ufn()
is used to turn a DN as returned by
.BR ldap_get_dn (3)
into a more user-friendly form, stripping off all type names.  See
"Using the Directory to Achieve User Friendly Naming" (RFC 1781)
for more details on the UFN format.  Due to the ambigious nature
of the format, it is generally only used for display purposes.
The space for the UFN returned is obtained dynamically and the user
is responsible for freeing it via a call to
.BR ldap_memfree (3).
.SH ERRORS
If an error occurs in
.BR ldap_get_dn() ,
NULL is returned and the
.B ld_errno
field in the \fIld\fP parameter is set to indicate the error.  See
.BR ldap_error (3)
for a description of possible error codes.
.BR ldap_explode_dn() ,
.BR ldap_explode_rdn() ,
and
.B ldap_dn2ufn()
will return NULL with
.BR errno (3)
set appropriately in case of trouble.
.SH NOTES
These routines dyanamically allocate memory that the caller must free.
.SH SEE ALSO
.BR ldap(3),
.BR ldap_error(3),
.BR ldap_first_entry(3),
.BR ldap_memfree(3),
.BR ldap_value_free(3)
.SH ACKNOWLEDGEMENTS
.B	OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B	OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.