Tribblix: manual page: ldap.3ldap

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

NAME

ldap - Lightweight Directory Access Protocol package

SYNOPSIS

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

DESCRIPTION

The Lightweight Directory Access Protocol ("LDAP") package includes
various command line LDAP clients and a LDAP client library to
provide programmatic access to the LDAP protocol. This man page gives
an overview of the LDAP client library functions.

An application might use the LDAP client library functions as
follows. The application would initialize a LDAP session with a LDAP
server by calling ldap_init(3LDAP). Next, it authenticates to the
LDAP server by calling ldap_sasl_bind(3LDAP) and friends. It may
perform some LDAP operations and obtain results by calling
ldap_search(3LDAP) and friends. To parse the results returned from
these functions, it calls ldap_parse_result(3LDAP),
ldap_next_entry(3LDAP), and ldap_first_entry(3LDAP) and others. It
closes the LDAP session by calling ldap_unbind(3LDAP).

LDAP operations can be either synchronous or asynchronous. By
convention, the names of the synchronous functions end with "_s." For
example, a synchronous binding to the LDAP server can be performed by
calling ldap_sasl_bind_s(3LDAP). Complete an asynchronous binding
with ldap_sasl_bind(3LDAP). All synchronous functions return the
actual outcome of the operation, either LDAP_SUCCESS or an error
code. Asynchronous routines provide an invocation identifier which
can be used to obtain the result of a specific operation by passing
it to the ldap_result(3LDAP) function.

Initializing a LDAP session

Initializing a LDAP session involves calling the ldap_init(3LDAP)
function. However, the call does not actually open a connection to
the LDAP server. It merely initializes a LDAP structure that
represents the session. The connection is opened when the first
operation is attempted. Unlike ldap_init(), ldap_open(3LDAP) attempts
to open a connection with the LDAP server. However, the use of
ldap_open() is deprecated.

Authenticating to a LDAP server

The ldap_sasl_bind(3LDAP) and ldap_sasl_bind_s(3LDAP) functions
provide general and extensible authentication for an LDAP client to a
LDAP server. Both use the Simple Authentication Security Layer
(SASL). Simplified routines ldap_simple_bind(3LDAP) and
ldap_simple_bind_s(3LDAP) use cleartext passwords to bind to the LDAP
server. Use of ldap_bind(3LDAP) and ldap_bind_s(3LDAP)(3LDAP) is
deprecated.

Searching a LDAP directory

Search for an entry in a LDAP directory by calling the
ldap_search_ext(3LDAP) or the ldap_search_ext_s(3LDAP) functions.
These functions support LDAPv3 server controls, client controls and
variable size and time limits as arguments for each search operation.
ldap_search(3LDAP) and ldap_search_s(3LDAP) are identical functions
but do not support the controls and limits as arguments to the call.

Adding or Deleting an entry

Use ldap_add_ext(3LDAP) and ldap_delete_ext(3LDAP) to add or delete
entries in a LDAP directory server. The synchronous counterparts to
these functions are ldap_add_ext_s(3LDAP) and
ldap_delete_ext_s(3LDAP). The ldap_add(3LDAP), ldap_add_s(3LDAP),
ldap_delete(3LDAP), and ldap_delete_s(3LDAP) provide identical
functionality to add and to delete entries, but they do not support
LDAP v3 server and client controls.

Modifying Entries

Use ldap_modify_ext(3LDAP) and ldap_modify_ext_s(3LDAP) to modify an
existing entry in a LDAP server that supports for LDAPv3 server and
client controls. Similarly, use ldap_rename(3LDAP) and
ldap_rename_s(3LDAP) to change the name of an LDAP entry. The
ldap_modrdn(3LDAP), ldap_modrdn2(3LDAP), ldap_modrdn_s(3LDAP) and
ldap_modrdn2_s(3LDAP) interfaces are deprecated.

Obtaining Results

Use ldap_result(3LDAP) to obtain the results of a previous
asynchronous operation. For all LDAP operations other than search,
only one message is returned. For the search operation, a list of
result messages can be returned.

Handling Errors and Parsing Results

Use the ldap_parse_result(3LDAP), ldap_parse_sasl_bind_result(3LDAP),
and the ldap_parse_extended_result(3LDAP) functions to extract
required information from results and to handle the returned errors.
To convert a numeric error code into a null-terminated character
string message describing the error, use ldap_err2string(3LDAP). The
ldap_result2error(3LDAP) and ldap_perror(3LDAP) functions are
deprecated. To step through the list of messages in a result returned
by ldap_result(), use ldap_first_message(3LDAP) and
ldap_next_message(3LDAP). ldap_count_messages(3LDAP) returns the
number of messages contained in the list.

You can use ldap_first_entry(3LDAP) and ldap_next_entry(3LDAP) to
step through and obtain a list of entries from a list of messages
returned by a search result. ldap_count_entries(3LDAP) returns the
number of entries contained in a list of messages. Call either
ldap_first_attribute(3LDAP) and ldap_next_attribute(3LDAP) to step
through a list of attributes associated with an entry. Retrieve the
values of a given attribute by calling ldap_get_values(3LDAP) and
ldap_get_values_len(3LDAP). Count the number of values returned by
using ldap_count_values(3LDAP) and ldap_count_values_len(3LDAP).

Use the ldap_get_lang_values(3LDAP) and
ldap_get_lang_values_len(3LDAP) to return an attribute's values that
matches a specified language subtype. The ldap_get_lang_values()
function returns an array of an attribute's string values that
matches a specified language subtype. To retrieve the binary data
from an attribute, call the ldap_get_lang_values_len() function
instead.

Uniform Resource Locators (URLS)
You can use the ldap_url(3LDAP)functions to test a URL to verify that
it is an LDAP URL, to parse LDAP URLs into their component pieces, to
initiate searches directly using an LDAP URL, and to retrieve the URL
associated with a DNS domain name or a distinguished name.

User Friendly Naming

The ldap_ufn(3LDAP) functions implement a user friendly naming scheme
by means of LDAP. This scheme allows you to look up entries using
fuzzy, untyped names like "mark smith, umich, us".

Caching

The ldap_memcache(3LDAP) functions provide an in-memory client side
cache to store search requests. Caching improves performance and
reduces network bandwidth when a client makes repeated requests.

Utility Functions

There are also various utility functions. You can use the
ldap_sort(3LDAP) functions are used to sort the entries and values
returned by means of the ldap search functions. The
ldap_friendly(3LDAP) functions will map from short two letter country
codes or other strings to longer "friendlier" names. Use the
ldap_charset(3LDAP) functions to translate to and from the T.61
character set that is used for many character strings in the LDAP
protocol.

Generating Filters

Make calls to ldap_init_getfilter(3LDAP) and ldap_search(3LDAP) to
generate filters to be used in ldap_search(3LDAP) and
ldap_search_s(3LDAP). ldap_init_getfilter() reads ldapfilter.conf(5),
the LDAP configuration file, while ldap_init_getfilter_buf() reads
the configuration information from buf of length buflen.
ldap_getfilter_free(3LDAP) frees memory that has been allocated by
means of ldap_init_getfilter().

BER Library

The LDAP package includes a set of lightweight Basic Encoding Rules
("BER)" functions. The LDAP library functions use the BER functions
to encode and decode LDAP protocol elements through the slightly
simplified BER defined by LDAP. They are not normally used directly
by an LDAP application program will not normally use the BER
functions directly. Instead, these functions provide a printf() and
scanf()-like interface, as well as lower-level access.

LIST OF INTERFACES

ldap_open(3LDAP)

Deprecated. Use ldap_init(3LDAP).

ldap_init(3LDAP)

Initialize a session with a LDAP server without opening a
connection to a server.

ldap_result(3LDAP)

Obtain the result from a previous asynchronous operation.

ldap_abandon(3LDAP)

Abandon or abort an asynchronous operation.

ldap_add(3LDAP)

Asynchronously add an entry

ldap_add_s(3LDAP)

Synchronously add an entry.

ldap_add_ext(3LDAP)

Asynchronously add an entry with support for LDAPv3 controls.

ldap_add_ext_s(3LDAP)

Synchronously add an entry with support for LDAPv3 controls.

ldap_bind(3LDAP)

Deprecated. Use ldap_sasl_bind(3LDAP) or ldap_simple_bind(3LDAP).

ldap_sasl_bind(3LDAP)

Asynchronously bind to the directory using SASL authentication

ldap_sasl_bind_s(3LDAP)

Synchronously bind to the directory using SASL authentication

ldap_bind_s(3LDAP)

Deprecated. Use ldap_sasl_bind_s(3LDAP) or
ldap_simple_bind_s(3LDAP).

ldap_simple_bind(3LDAP)

Asynchronously bind to the directory using simple authentication.

ldap_simple_bind_s(3LDAP)

Synchronously bind to the directory using simple authentication.

ldap_unbind(3LDAP)

Synchronously unbind from the LDAP server, close the connection,
and dispose the session handle.

ldap_unbind_ext(3LDAP)

Synchronously unbind from the LDAP server and close the
connection. ldap_unbind_ext() allows you to explicitly include
both server and client controls in the unbind request.

ldap_set_rebind_proc(3LDAP)

Set callback function for obtaining credentials from a referral.

ldap_memcache_init(3LDAP)

Create the in-memory client side cache.

ldap_memcache_set(3LDAP)

Associate an in-memory cache that has been already created by
calling the ldap_memcache_init(3LDAP) function with an LDAP
connection handle.

ldap_memcache_get(3LDAP)

Get the cache associated with the specified LDAP structure.

ldap_memcache_flush(3LDAP)

Flushes search requests from the cache.

ldap_memcache_destroy(3LDAP)

Frees the specified LDAPMemCache structure pointed to by cache
from memory.

ldap_memcache_update(3LDAP)

Checks the cache for items that have expired and removes them.

ldap_compare(3LDAP)

Asynchronous compare with a directory entry.

ldap_compare_s(3LDAP)

Synchronous compare with a directory entry.

ldap_compare_ext(3LDAP)

Asynchronous compare with a directory entry, with support for
LDAPv3 controls.

ldap_compare_ext_s(3LDAP)

Synchronous compare with a directory entry, with support for
LDAPv3 controls.

ldap_control_free(3LDAP)

Dispose of an LDAP control.

ldap_controls_free(3LDAP)

Dispose of an array of LDAP controls.

ldap_delete(3LDAP)

Asynchronously delete an entry.

ldap_delete_s(3LDAP)

Synchronously delete an entry.

ldap_delete_ext(3LDAP)

Asynchronously delete an entry, with support for LDAPv3 controls.

ldap_delete_ext_s(3LDAP)

Synchronously delete an entry, with support for LDAPv3 controls.

ldap_init_templates(3LDAP)

Read a sequence of templates from a LDAP template configuration
file.

ldap_init_templates_buf(3LDAP)

Read a sequence of templates from a buffer.

ldap_free_templates(3LDAP)

Dispose of the templates allocated.

ldap_first_reference(3LDAP)

Step through a list of continuation references from a search
result.

ldap_next_reference(3LDAP)

Step through a list of continuation references from a search
result.

ldap_count_references(3LDAP)

Count the number of messages in a search result.

ldap_first_message(3LDAP)

Step through a list of messages in a search result.

ldap_count_messages(3LDAP)

Count the messages in a list of messages in a search result.

ldap_next_message(3LDAP)

Step through a list of messages in a search result.

ldap_msgtype(3LDAP)

Return the type of LDAP message.

ldap_first_disptmpl(3LDAP)

Get first display template in a list.

ldap_next_disptmpl(3LDAP)

Get next display template in a list.

ldap_oc2template(3LDAP)

Return template appropriate for the objectclass.

ldap_name2template(3LDAP)

Return named template

ldap_tmplattrs(3LDAP)

Return attributes needed by the template.

ldap_first_tmplrow(3LDAP)

Return first row of displayable items in a template.

ldap_next_tmplrow(3LDAP)

Return next row of displayable items in a template.

ldap_first_tmplcol(3LDAP)

Return first column of displayable items in a template.

ldap_next_tmplcol(3LDAP)

Return next column of displayable items in a template.

ldap_entry2text(3LDAP)

Display an entry as text by using a display template.

ldap_entry2text_search(3LDAP)

Search for and display an entry as text by using a display
template.

ldap_vals2text(3LDAP)

Display values as text.

ldap_entry2html(3LDAP)

Display an entry as HTML (HyperText Markup Language) by using a
display template.

ldap_entry2html_search(3LDAP)

Search for and display an entry as HTML by using a display
template.

ldap_vals2html(3LDAP)

Display values as HTML.

ldap_perror(3LDAP)

Deprecated. Use ldap_parse_result(3LDAP).

ldap_result2error(3LDAP)

Deprecated. Use ldap_parse_result(3LDAP).

ldap_err2string(3LDAP)

Convert LDAP error indication to a string.

ldap_first_attribute(3LDAP)

Return first attribute name in an entry.

ldap_next_attribute(3LDAP)

Return next attribute name in an entry.

ldap_first_entry(3LDAP)

Return first entry in a chain of search results.

ldap_next_entry(3LDAP)

Return next entry in a chain of search results.

ldap_count_entries(3LDAP)

Return number of entries in a search result.

ldap_friendly_name(3LDAP)

Map from unfriendly to friendly names.

ldap_free_friendlymap(3LDAP)

Free resources used by ldap_friendly(3LDAP).

ldap_get_dn(3LDAP)

Extract the DN from an entry.

ldap_explode_dn(3LDAP)

Convert a DN into its component parts.

ldap_explode_dns(3LDAP)

Convert a DNS-style DN into its component parts (experimental).

ldap_is_dns_dn(3LDAP)

Check to see if a DN is a DNS-style DN (experimental).

ldap_dns_to_dn(3LDAP)

Convert a DNS domain name into an X.500 distinguished name.

ldap_dn2ufn(3LDAP)

Convert a DN into user friendly form.

ldap_get_values(3LDAP)

Return an attribute's values.

ldap_get_values_len(3LDAP)

Return an attribute's values with lengths.

ldap_value_free(3LDAP)

Free memory allocated by ldap_get_values(3LDAP).

ldap_value_free_len(3LDAP)

Free memory allocated by ldap_get_values_len(3LDAP).

ldap_count_values(3LDAP)

Return number of values.

ldap_count_values_len(3LDAP)

Return number of values.

ldap_init_getfilter(3LDAP)

Initialize getfilter functions from a file.

ldap_init_getfilter_buf(3LDAP)

Initialize getfilter functions from a buffer.

ldap_getfilter_free(3LDAP)

Free resources allocated by ldap_init_getfilter(3LDAP).

ldap_getfirstfilter(3LDAP)

Return first search filter.

ldap_getnextfilter(3LDAP)

Return next search filter.

ldap_build_filter(3LDAP)

Construct an LDAP search filter from a pattern.

ldap_setfilteraffixes(3LDAP)

Set prefix and suffix for search filters.

ldap_modify(3LDAP)

Asynchronously modify an entry.

ldap_modify_s(3LDAP)

Synchronously modify an entry.

ldap_modify_ext(3LDAP)

Asynchronously modify an entry, return value, and place message.

ldap_modify_ext_s(3LDAP)

Synchronously modify an entry, return value, and place message.

ldap_mods_free(3LDAP)

Free array of pointers to mod structures used by
ldap_modify(3LDAP).

ldap_modrdn2(3LDAP)

Deprecated. Use ldap_rename(3LDAP) instead.

ldap_modrdn2_s(3LDAP)

Deprecated. Use ldap_rename_s(3LDAP) instead.

ldap_modrdn(3LDAP)

Deprecated. Use ldap_rename(3LDAP) instead.

ldap_modrdn_s(3LDAP)

Depreciated. Use ldap_rename_s(3LDAP) instead.

ldap_rename(3LDAP)

Asynchronously modify the name of an LDAP entry.

ldap_rename_s(3LDAP)

Synchronously modify the name of an LDAP entry.

ldap_msgfree(3LDAP)

Free result messages.

ldap_parse_result(3LDAP)

Search for a message to parse.

ldap_parse_extended_result(3LDAP)

Search for a message to parse.

ldap_parse_sasl_bind_result(3LDAP)

Search for a message to parse.

ldap_search(3LDAP)

Asynchronously search the directory.

ldap_search_s(3LDAP)

Synchronously search the directory.

ldap_search_ext(3LDAP)

Asynchronously search the directory with support for LDAPv3
controls.

ldap_search_ext_s(3LDAP)

Synchronously search the directory with support for LDAPv3
controls.

ldap_search_st(3LDAP)

Synchronously search the directory with support for a local
timeout value.

ldap_ufn_search_s(3LDAP)

User friendly search the directory.

ldap_ufn_search_c(3LDAP)

User friendly search the directory with cancel.

ldap_ufn_search_ct(3LDAP)

User friendly search the directory with cancel and timeout.

ldap_ufn_setfilter(3LDAP)

Set filter file used by ldap_ufn(3LDAP) functions.

ldap_ufn_setprefix(3LDAP)

Set prefix used by ldap_ufn(3LDAP) functions.

ldap_ufn_timeout(3LDAP)

Set timeout used by ldap_ufn(3LDAP) functions.

ldap_is_ldap_url(3LDAP)

Check a URL string to see if it is an LDAP URL.

ldap_url_parse(3LDAP)

Break up an LDAP URL string into its components.

ldap_free_urldesc(3LDAP)

Free an LDAP URL structure.

ldap_url_search(3LDAP)

Asynchronously search by using an LDAP URL.

ldap_url_search_s(3LDAP)

Synchronously search by using an LDAP URL.

ldap_url_search_st(3LDAP)

Asynchronously search by using an LDAP URL, with support for a
local timeout value.

ldap_dns_to_url(3LDAP)

Locate the LDAP URL associated with a DNS domain name.

ldap_dn_to_url(3LDAP)

Locate the LDAP URL associated with a distinguished name.

ldap_init_searchprefs(3LDAP)

Initialize searchprefs functions from a file.

ldap_init_searchprefs_buf(3LDAP)

Initialize searchprefs functions from a buffer.

ldap_free_searchprefs(3LDAP)

Free memory allocated by searchprefs functions.

ldap_first_searchobj(3LDAP)

Return first searchpref object.

ldap_next_searchobj(3LDAP)

Return next searchpref object.

ldap_sort_entries(3LDAP)

Sort a list of search results.

ldap_sort_values(3LDAP)

Sort a list of attribute values.

ldap_sort_strcasecmp(3LDAP)

Case insensitive string comparison.

ldap_set_string_translators(3LDAP)

Set character set translation functions used by LDAP library.

ldap_translate_from_t61(3LDAP)

Translate from the T.61 character set to another character set.

ldap_translate_to_t61(3LDAP)

Translate to the T.61 character set from another character set.

ldap_enable_translation(3LDAP)

Enable or disable character translation for an LDAP entry result.

ldap_version(3LDAP)

Get version information about the LDAP SDK for C.

ldap_get_lang_values(3LDAP)

Return an attribute's value that matches a specified language
subtype.

ldap_get_lang_values_len(3LDAP)

Return an attribute's value that matches a specified language
subtype along with lengths.

ldap_get_entry_controls(3LDAP)

Get the LDAP controls included with a directory entry in a set of
search results.

ldap_get_option(3LDAP)

Get session preferences in an LDAP structure.

ldap_set_option(3LDAP)

Set session preferences in an LDAP structure.

ldap_memfree(3LDAP)

Free memory allocated by LDAP API functions.

ATTRIBUTES