Tribblix: manual page: ldap

LDAP_URL(3LDAP) LDAP Library Functions LDAP_URL(3LDAP)

NAME

ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn,
ldap_free_urldesc, ldap_url_search, ldap_url_search_s,
ldap_url_search_st, ldap_dns_to_url, ldap_dn_to_url - LDAP Uniform
Resource Locator functions

SYNOPSIS

cc[ flag... ] file... -lldap[ library... ]
#include <lber.h>
#include <ldap.h>

int ldap_is_ldap_url(char *url);

int ldap_url_parse(char *url, LDAPURLDesc **ludpp);

int ldap_url_parse_nodn(char *url, LDAPURLDesc **ludpp);

ldap_free_urldesc(LDAPURLDesc *ludp);

int ldap_url_search(LDAP *ld, char *url, int attrsonly);

int ldap_url_search_s(LDAP *ld, char *url,
int attrsonly, LDAPMessage **res);

int ldap_url_search_st(LDAP *ld, char *url, int attrsonly,
struct timeval *timeout, LDAPMessage **res);

char *ldap_dns_to_url(LDAP *ld, char *dns_name, char *attrs,
char *scope, char *filter);

char *ldap_dn_to_url(LDAP *ld, char *dn, int nameparts);

DESCRIPTION

These functions support the use of LDAP URLs (Uniform Resource
Locators). The following shows the formatting used for LDAP URLs.

ldap://hostport/dn[?attributes[?scope[?filter]]]

where:

hostport
Host name with an optional :portnumber.

dn
Base DN to be used for an LDAP search operation.

attributes
Comma separated list of attributes to be retrieved.

scope
One of these three strings: base one sub
(default=base).

filter
LDAP search filter as used in a call to
ldap_search(3LDAP).

The following is an example of an LDAP URL:

ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich

URLs preceded URL: or wrapped in angle-brackets are tolerated. URLs
can also be preceded by URL: and wrapped in angle-brackets.

ldap_is_ldap_url() returns a non-zero value if url looks like an LDAP
URL (as opposed to some other kind of URL). It can be used as a quick
check for an LDAP URL; the ldap_url_parse() function should be used
if a more thorough check is needed.

ldap_url_parse() breaks down an LDAP URL passed in url into its
component pieces. If successful, zero is returned, an LDAP URL
description is allocated, filled in, and ludpp is set to point to it.
See RETURN VALUES for values returned upon error.

ldap_url_parse_nodn() acts just like ldap_url_parse() but does not
require dn in the LDAP URL.

ldap_free_urldesc() should be called to free an LDAP URL description
that was obtained from a call to ldap_url_parse().

ldap_url_search() initiates an asynchronous LDAP search based on the
contents of the url string. This function acts just like
ldap_search(3LDAP) except that many search parameters are pulled out
of the URL.

ldap_url_search_s() performs a synchronous LDAP search based on the
contents of the url string. This function acts just like
ldap_search_s(3LDAP) except that many search parameters are pulled
out of the URL.

ldap_url_search_st() performs a synchronous LDAP URL search with a
specified timeout. This function acts just like ldap_search_st(3LDAP)
except that many search parameters are pulled out of the URL.

ldap_dns_to_url() locates the LDAP URL associated with a DNS domain
name. The supplied DNS domain name is converted into a distinguished
name. The directory entry specified by that distinguished name is
searched for a labeled URI attribute. If successful then the
corresponding LDAP URL is returned. If unsuccessful then that entry's
parent is searched and so on until the target distinguished name is
reduced to only two nameparts. If dns_name is NULL then the
environment variable LOCALDOMAIN is used. If attrs is not NULL then
it is appended to the URL's attribute list. If scope is not NULL then
it overrides the URL's scope. If filter is not NULL then it is merged
with the URL's filter. If an error is encountered then zero is
returned, otherwise a string URL is returned. The caller should free
the returned string if it is non-zero.

ldap_dn_to_url() locates the LDAP URL associated with a distinguished
name. The number of nameparts in the supplied distinguished name must
be provided. The specified directory entry is searched for a
labeledURI attribute. If successful then the LDAP URL is returned.
If unsuccessful then that entry's parent is searched and so on until
the target distinguished name is reduced to only two nameparts. If an
error is encountered then zero is returned, otherwise a string URL is
returned. The caller should free the returned string if it is non-
zero.

RETURN VALUES

Upon error, one of these values is returned for ldap_url_parse():

LDAP_URL_ERR_BADSCOPE
URL scope string is invalid.

LDAP_URL_ERR_HOSTPORT
URL hostport is invalid.

LDAP_URL_ERR_MEM
Can't allocate memory space.

LDAP_URL_ERR_NODN
URL has no DN (required).

LDAP_URL_ERR_NOTLDAP
URL doesn't begin with ldap://.

ATTRIBUTES

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ATTRIBUTES

SEE ALSO