LDAPGETDN(3) LDAPGETDN(3)
NAME
ldapgetdn, ldapexplodedn, ldapexploderdn, ldapdn2ufn - LDAP DN
handling routines
LIBRARY
OpenLDAP LDAP (libldap, -lldap)
SYNOPSIS
##include <>
char **ldapgetdn( LDAP **ld,, LDAPessage **entry )
int ldapstr2dn( const char **str,, LDAPDN ****dn,, unsigned flags )
int ldapdn2str( LDAPDN **dn,, char ****str,, unsigned flags )
char ****ldapexplodedn( const char **dn,, int notypes )
char ****ldapexploderdn( const char **rdn,, int notypes )
char **ldapdn2ufn( const char ** dn )
char **ldapdn2dcedn( const char ** dn )
char **ldapdcedn2dn( const char ** dn )
char **ldapdn2adcanonical( const 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 ldapgetdn() routine takes an entry as returned by
ldapfirstentry(3) or ldapnextentry(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 ldapmemfree(3).
ldapstr2dn() parses a string representation of a distinguished name
contained in str into its components, which are stored in dn as
ldapava structures, arranged in LDAPAVA,, LDAPRDN,, and LDAPDN terms,
defined as:
typedef struct ldapava {{
char **laattr;;
struct berval **lavalue;;
unsigned laflags;;
}} LDAPAVA;;
typedef LDAPAVA**** LDAPRDN;;
typedef LDAPRDN**** LDAPDN;;
The attribute types and the attribute values are not normalized. The
laflags can be either LDAPAVASTRING or LDAPAVABINARY,, the latter
meaning that the value is BER/DER encoded and thus must be represented
as, quoting from RFC 2253, " ... an octothorpe character ('#' ASCI 35)
followed by the hexadecimal representation of each of the bytes of the
BER encoding of the X.500 AttributeValue." The flags parameter to
ldapstr2dn() can be
LDAPDNFORMATLDAPV3
LDAPDNFORMATLDAPV2
LDAPDNFORMATDCE
which defines what DN syntax is expected (according to RFC 2253, RFC
1779 and DCE, respectively). The format can be ORed to the flags
LDAPDNPNOSPACES
LDAPDNPNOSPACEAFTERDN
...
LDAPDNPEDANTIC
The latter is a shortcut for all the previous limitations.
LDAPDNPNOSPACES does not allow extra spaces in the dn; the default
is to silently eliminate spaces around AVA separators ('='), RDN compo-
nent separators (']' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separa-
tors (',' LDAPv3/LDAPv2 or '/' for DCE).
LDAPDNPNOSPACEAFTERDN does not allow a single space after RDN
separators.
ldapdn2str() performs the inverse operation, yielding in str a string
representation of dn. It allows the same values for flags as
ldapstr2dn(),, plus
LDAPDNFORMATUFN
LDAPDNFORMATADCANONICAL
for user-friendly naming (RFC 1781) and AD canonical.
The following routines are viewed as deprecated in favor of
ldapstr2dn() and ldapdn2str(). They are provided to support legacy
applications.
The ldapexplodedn() routine takes a DN as returned by ldapgetdn()
and breaks it up into its component parts. Each part is known as a
Relative Distinguished Name, or RDN. ldapexplodedn() returns a NUL-
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", NUL } or { "Bob", "US", NUL },
depending on whether notypes was 0 or 1, respectively. Assertion val-
ues in RDN strings may included escaped characters. The result can be
freed by calling ldapvaluefree(3).
Similarly, the ldapexploderdn() routine takes an RDN as returned by
ldapexplodedn(dn,,00) and breaks it up into its "type=value" component
parts (or just "value", if the notypes parameter is set). Note the
value is not unescaped. The result can be freed by calling
ldapvaluefree(3).
ldapdn2ufn() is used to turn a DN as returned by ldapgetdn(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 free-
ing it via a call to ldapmemfree(3).
ldapdn2dcedn() is used to turn a DN as returned by ldapgetdn(3) into
a DCE-style DN, e.g. a string with most-significant to least signifi-
cant rdns separated by slashes ('/'); rdn components are separated by
commas (','). Only printable chars (e.g. LDAPv2 printable string) are
allowed, at least in this implementation. ldapdcedn2dn() performs the
opposite operation. ldapdn2adcanonical() turns a DN into a AD canon-
ical name, which is basically a DCE dn with attribute types omitted.
The trailing domain, if present, is turned in a DNS-like domain. The
space for the returned value is obtained dynamically and the user is
responsible for freeing it via a call to ldapmemfree(3).
ERORS
If an error occurs in ldapgetdn(), NUL is returned and the lderrno
field in the ld parameter is set to indicate the error. See
ldaperror(3) for a description of possible error codes.
ldapexplodedn(), ldapexploderdn(), ldapdn2ufn(),, ldapdn2dcedn(),,
ldapdcedn2dn(),, and ldapdn2adcanonical() will return NUL with
errno(3) set appropriately in case of trouble.
NOTES
These routines dynamically allocate memory that the caller must free.
SEE ALSO
ldap(3), ldaperror(3), ldapfirstentry(3), ldapmemfree(3),
ldapvaluefree(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.2.19 2004/11/26 LDAPGETDN(3)
|
