The Lightweight Directory Access Protocol provides access to
X.500 directory services. The services may be stand-alone
part of a distributed directory service. This API supports
LDAP over TCP, LDAP over SSL, and LDAP over IPC (UNIX domain
sockets).
The OpenLDAP LDAP package includes a stand-alone server in
slapd(8),
various LDAP clients, and an LDAP client library used to provide
programmatic access to the LDAP protocol. This man page gives an
overview of the LDAP library routines.
Both synchronous and asynchronous APIs are provided. Also included are
various routines to parse the results returned from these routines.
These routines are found in the -lldap library.
The basic interaction is as follows. A session handle associated
with created using
ldap_init(3).
The underlying session is established upon first use which is
commonly an LDAP bind operation. The LDAP bind operation is
performed by calling one of
ldap_sasl_bind(3)
and friends. Next, other operations are performed
by calling one of the synchronous or asynchronous routines (e.g.,
ldap_search_ext_s(3)
or
ldap_search_ext(3)
followed by
ldap_result(3)).
Results returned from these routines are interpreted by calling the
LDAP parsing routines such as
ldap_parse_result(3).
The LDAP association and underlying connection is terminated by calling
ldap_unbind_ext(3).
Errors can be interpreted by calling
ldap_err2string(3).
SEARCH FILTERS
Search filters to be passed to the ldap search routines can be
constructed by hand, or by calling the
ldap_getfilter(3)
routines, which use the
ldapgetfilter.conf(5)
file to turn a string (presumably that a user has typed) into a series
of search filters.
DISPLAYING RESULTS
Results obtained from the ldap search routines can be output by hand,
by calling
ldap_first_entry(3)
and
ldap_next_entry(3)
to step through
the entries returned,
ldap_first_attribute(3)
and
ldap_next_attribute(3)
to step through an entry's attributes, and
ldap_get_values(3)
to retrieve a given attribute's value. Attribute values
may or may not be displayable.
Alternatively, the entry can be output automatically by calling
the
ldap_entry2text(3),
ldap_entry2text_search(3),
ldap_entry2html(3),
or
ldap_entry2html_search(3)
routines. These routines look up the object
class of the entry they are passed in the
ldaptemplates.conf(5)
file to decide which attributes to display and how to display them.
Output is handled via a routine passed in as a parameter.
UNIFORM RESOURCE LOCATORS (URLS)
The
ldap_url(3)
routines can be used test a URL to see if it is an LDAP URL, to parse LDAP
URLs into their component pieces, and to initiate searches directly using
an LDAP URL.
CACHING
The
ldap_cache(3)
routines implement a local client caching scheme,
providing a substantial performance increase for repeated queries.
UTILITY ROUTINES
Also provided are various utility routines. The
ldap_sort(3)
routines are used to sort the entries and values returned via
the ldap search routines. The
ldap_friendly(3)
routines are
used to map from short two letter country codes (or other strings)
to longer "friendlier" names.
BER LIBRARY
Also included in the distribution is a set of lightweight Basic
Encoding Rules routines. These routines are used by the LDAP library
routines to encode and decode LDAP protocol elements using the
(slightly simplified) Basic Encoding Rules defined by LDAP. They are
not normally used directly by an LDAP application program excepting
in the handling of controls and extended operations. The
routines provide a printf and scanf-like interface, as well as
lower-level access. These routines are found in the -llber
library.