mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
139 lines
3.8 KiB
Groff
139 lines
3.8 KiB
Groff
.TH LDAP_GET_DN 3 "22 September 1998" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-1999 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_is_dns_dn, ldap_explode_dns \- LDAP DN handling routines
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <ldap.h>
|
|
.LP
|
|
.ft B
|
|
char *ldap_get_dn(ld, entry)
|
|
.ft
|
|
LDAP *ld;
|
|
LDAPMessage *entry;
|
|
.LP
|
|
.ft B
|
|
char **ldap_explode_dn(dn, notypes)
|
|
.ft
|
|
char *dn;
|
|
int notypes;
|
|
.LP
|
|
.ft B
|
|
char **ldap_explode_rdn(rdn, notypes)
|
|
.ft
|
|
char *rdn;
|
|
int notypes;
|
|
.LP
|
|
.ft B
|
|
char *ldap_dn2ufn(dn)
|
|
.ft
|
|
char *dn;
|
|
.LP
|
|
.ft B
|
|
int ldap_is_dns_dn(dn)
|
|
.ft
|
|
char *dn;
|
|
.LP
|
|
.ft B
|
|
char **ldap_explode_dns(dn)
|
|
.ft
|
|
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 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.
|
|
.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). 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
|
|
.B 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
|
|
.BR ldap_memfree (3).
|
|
.LP
|
|
.B 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.
|
|
.LP
|
|
.B ldap_explode_dns()
|
|
takes a DNS-style DN and breaks it up into its
|
|
component parts.
|
|
.B 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
|
|
.BR ldap_value_free (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() ,
|
|
.B ldap_explode_dns()
|
|
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.
|