MAN page from Mandrake Other ldap-devel-3.3-3.i386.rpm

LDAP_GET_DN

Section: C Library Functions (3)
Updated: 16 June 1995
Index

NAME

ldap_get_dn, ldap_explode_dn, ldap_dn2ufn, ldap_is_dns_dn, ldap_explode_dns - LDAP DN handling routines

SYNOPSIS

#include <lber.h>#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_dn2ufn(dn)char *dn;int ldap_is_dns_dn(dn)char *dn;char **ldap_explode_dns(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 1779 "A String Representation ofDistinguished Names", unless it is an experimental DNS-style DNwhich takes the form of an RFC 822 mail address.

Theldap_get_dn()routine takes an entry as returned byldap_first_entry(3)orldap_next_entry(3)and returns a copy ofthe entry's DN. Space for the DN will have been obtained viamalloc(3),and should be freed by the caller by a call tofree(3).

Theldap_explode_dn()routine takes a DN as returned byldap_get_dn()and breaks it up into its component parts. Each part is known as aRelative Distinguished Name, or RDN.ldap_explode_dn()returns aNULL-terminated array, each component of which contains an RDN from theDN. The notypes parameter is used to request that only the RDNvalues 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 callingldap_value_free(3).

ldap_dn2ufn()is used to turn a DN as returned byldap_get_dn()into a more user-friendly form, stripping off type names. SeeRFC 1781 "Using the Directory to Achieve User Friendly Naming"for more details on the UFN format. The space for the UFN returnedis obtained by a call tomalloc(3),and the user is responsible for freeing it via a call tofree(3).

ldap_is_dns_dn()returns non-zero if the dn string is an experimentalDNS-style DN (generally in the form of an RFC 822 e-mail address). Itreturns 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 itscomponent 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 callingldap_value_free(3).

ERRORS

If an error occurs inldap_get_dn(),NULL is returned and theld_errnofield in the ld parameter is set to indicate the error. Seeldap_error(3)for a description of possible error codes.ldap_explode_dn(),ldap_explode_dns()andldap_dn2ufn()will return NULL witherrno(3)set appropriately in case of trouble.

NOTES

These routines malloc memory that the caller must free.

This document was created byman2html,using the manual pages.