Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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);
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.
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.
See attributes(7) for a description of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Evolving |
ldap (3LDAP), ldap_error (3LDAP), ldap_first_entry (3LDAP), ldap_value_free (3LDAP)
These functions allocate memory that the caller must free.