ChorusOS man pages section 3LDAP: LDAP Library

ldap(3LDAP)

NAME

ldap- Lightweight Directory Access Protocol ibrary

SYNOPSIS

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

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

The Lightweight Directory Access Protocol client library supplied with ChorusOS provides programmatic access to the LDAP protocol. This man page gives an overview of the LDAP client library functions that have been implemented and validated in ChorusOS.

An example of how an application might use the LDAP client library functions follows. Initialize a LDAP session with a LDAP server by calling ldap_init(3LDAP). Next, authenticate to the LDAP server by calling ldap_sasl_bind(3LDAP) and other related calls. Perform some LDAP operations and obtain results by calling ldap_search(3LDAP)and other related calls. Results returned from these functions can be parsed by calling the ldap_parse_result(3LDAP), ldap_first_entry(3LDAP), ldap_next_entry(3LDAP) and other related calls. Close the LDAP session by calling ldap_unbind(3LDAP).

LDAP operations can be either synchronous or asynchronous. The names of the sychronous functions end is _s. For example, a synchronous binding to the LDAP server can be performed by calling the ldap_sasl_bind_s(3LDAP). An asynchronous binding can be done with ldap_sasl_bind(). All synchronous functions return the actual outcome of the operation (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() function. However it 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. Use of ldap_open() is deprecated.

Authenticating to a LDAP server

The ldap_sasl_bind() and ldap_sasl_bind_s() functions provide general and extensible authenticaton 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() and ldap_bind_s() is deprecated.

Searching a LDAP directory

Searching for an entry in a LDAP directory can be performed 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 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

Adding or deleting entries in a LDAP directory server can be performed by ldap_add_ext(3LDAP) and ldap_delete_ext(3LDAP) respectively. The synchronous counterparts to these functions are ldap_add_ext_s(3LDAP) and ldap_delete_ext_s(3LDAP). Similar to the search functions described above, ldap_add(3LDAP), ldap_add_s(3LDAP), ldap_delete(3LDAP), and ldap_delete_s(3LDAP) are identical functions with no support for LDAP v3 server and client controls.

Modifying Entries

As described for the search, add or delete LDAP functions, ldap_modify_ext(3LDAP) and ldap_modify_ext_s(3LDAP) can be used to modify an existing entry in a LDAP server with support for LDAPv3 server and client controls. Similarly ldap_rename(3LDAP) and ldap_rename_s(3LDAP) can be used to change the name of an LDAP entry. Use of ldap_modrdn(3LDAP) and ldap_modrdn_s(3LDAP).

Obtaining Results

ldap_result() is used 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

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

The ldap_first_entry() and ldap_next_entry() functions are used 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. Next, the ldap_first_attribute(3LDAP) and ldap_next_attribute(3LDAP) functions can be called to step through a list of attributes associated with an entry. Finally, ldap_get_values(3LDAP) and ldap_get_values_len(3LDAP) are used to retrieve the values of a given attribute. ldap_count_values(3LDAP) and ldap_count_values_len(3LDAP) are used to count the number of values returned.

BER Library

Also included in the distribution is a set of lightweight Basic Encoding Rules functions. These functions are used by the LDAP library functions 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. The functions provide a printf and scanf-like interface, as well as lower-level access.

Index

ldap_open(3LDAP): open a connection to an LDAP server
ldap_init(3LDAP): initialize the LDAP library without opening a connection to a server
ldap_result(3LDAP): wait for the result from an asynchronous operation
ldap_abandon(3LDAP): abandon (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, return value and place message
ldap_add_ext_s(3LDAP): synchronously add an entry, return value and place message
ldap_bind(3LDAP): asynchronously bind to the directory
ldap_bind_s(3LDAP): synchronously bind to the directory
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 and close the connection
ldap_unbind_s(3LDAP): equivalent to ldap_unbind(3LDAP)
ldap_compare(3LDAP): asynchronous compare to a directory entry
ldap_compare_s(3LDAP): synchronous compare to a directory entry
ldap_compare_ext(3LDAP): asynchronous compare to a directory entry, return value and place message
ldap_compare_ext_s(3LDAP): synchronous compare to a directory entry, return value and place message
ldap_delete(3LDAP): asynchronously delete an entry
ldap_delete_s(3LDAP): synchronously delete an entry
ldap_delete_ext(3LDAP): asynchronously delete an entry, return value and place message
ldap_delete_ext_s(3LDAP): synchronously delete an entry, return value and place
ldap_first_reference(3LDAP): steps through ldap_result(3LDAP) message chain
ldap_count_references(3LDAP): counts the messages in an ldap_result() message chain
ldap_first_message(3LDAP): steps through ldap_result() message chain
ldap_count_messages(3LDAP): counts the messages in anldap_result() message chain
ldap_next_message(3LDAP): steps through anldap_result()message chain
ldap_msgtype(3LDAP): returns the type of LDAP message
ldap_perror(3LDAP)ldap_perror(3LDAP): print an LDAP error indication to standard error
ldap_result2error(3LDAP): extract LDAP error indication from LDAP result
ldap_errlist(3LDAP): list of ldap errors and their meanings
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_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 values with lengths
ldap_value_free(3LDAP): free memory allocated by ldap_get_values()
ldap_value_free_len(3LDAP): free memory allocated by ldap_get_values_len()
ldap_count_values(3LDAP): return number of values
ldap_count_values_len(3LDAP): return number of values
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, place message
ldap_modify_ext_s(3LDAP): synchronously modify an entry, return value, place message
ldap_mods_free(3LDAP): free array of pointers to mod structures used by ldap_modify()
ldap_modrdn(3LDAP): asynchronously modify the RDN of an entry
ldap_modrdn_s(3LDAP): synchronously modify the RDN of an entry
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 results allocated by ldap_result (3N)
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, return value and place message
ldap_search_ext_s(3LDAP): synchronously search the directory, return value and place message
ldap_search_st(3LDAP): synchronously search the directory with timeout

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 5.0 Last Revised December 2001