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