LDAP_GET_DN(3LDAP) LDAP Library Functions LDAP_GET_DN(3LDAP)
NAME
ldap_get_dn, ldap_explode_dn, ldap_dn2ufn, ldap_is_dns_dn,
ldap_explode_dns, ldap_dns_to_dn - LDAP DN handling functions
SYNOPSIS
cc[
flag... ]
file... -lldap[
library... ]
#include <lber.h>
#include <ldap.h>
char *ldap_get_dn(
LDAP *ld,
LDAPMessage *entry);
char **ldap_explode_dn(
char *dn,
int notypes);
char *ldap_dn2ufn(
char *dn);
int ldap_is_dns_dn(
char *dn);
char **ldap_explode_dns(
char *dn);
char *ldap_dns_to_dn(
char *dns_name,
int *nameparts);
DESCRIPTION
These functions 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 1779
A String Representation of Distinguished Names, unless it is an experimental DNS-style DN which
takes the form of an
RFC 822 mail address.
The
ldap_get_dn() function takes an
entry as returned by
ldap_first_entry(3LDAP) or
ldap_next_entry(3LDAP) and returns a copy of
the entry's DN. Space for the DN will have been obtained by means of
malloc(3C), and should be freed by the caller by a call to
free(3C).
The
ldap_explode_dn() function 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(3LDAP).
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 by a call to
malloc(3C), and the user is responsible for freeing it by means of a call
to
free(3C).
ldap_is_dns_dn() returns non-zero if the dn string is an experimental
DNS-style DN (generally in the form of an
RFC 822 e-mail address). It
returns zero if the dn appears to be an
RFC 1779 format DN.
ldap_explode_dns() takes a DNS-style DN and breaks it up into its
component parts.
ldap_explode_dns() returns a null-terminated array. For
example, the DN "mcs.umich.edu" will return { "mcs", "umich", "edu", NULL
}. The result can be freed by calling
ldap_value_free(3LDAP).
ldap_dns_to_dn() converts a DNS domain name into an X.500 distinguished
name. A string distinguished name and the number of nameparts is
returned.
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(3LDAP) for a description of possible error codes.
ldap_explode_dn(),
ldap_explode_dns() and
ldap_dn2ufn() will return
NULL with
errno(3C) set appropriately in case of trouble.
If an error in
ldap_dns_to_dn() is encountered zero is returned. The
caller should free the returned string if it is non-zero.
ATTRIBUTES
See
attributes(7) for a description of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Interface Stability | Evolving |
+--------------------+-----------------+
SEE ALSO
ldap(3LDAP),
ldap_error(3LDAP),
ldap_first_entry(3LDAP),
ldap_value_free(3LDAP)NOTES
These functions allocate memory that the caller must free.
January 27, 2002
LDAP_GET_DN(3LDAP)