Functions

To do this:	Call this function:
Initialize an LDAP session	`ldap_init()`
Initialize an LDAP session over SSL	`ldapssl_init()`
Set session preferences	`ldap_set_option()`
Get session preferences	`ldap_get_option()`
End an LDAP session	`ldap_unbind()` or `ldap_unbind_s()`

Authenticating to an LDAP Server

Call the following functions to authenticate to an LDAP server.

Table 18.2 Functions for authenticating to LDAP servers

To do this: Call this function:
Authenticate to an LDAP server using a password
ldap_simple_bind() or ldap_simple_bind_s()

Authenticate to an LDAP server using a SASL mechanism
ldap_sasl_bind() and ldap_parse_sasl_bind_result(), or ldap_sasl_bind_s()

Specify the function used to get authentication information when following referrals
ldap_set_rebind_proc()

To do this:	Call this function:
Authenticate to an LDAP server using a password	`ldap_simple_bind()` or `ldap_simple_bind_s()`
Authenticate to an LDAP server using a SASL mechanism	`ldap_sasl_bind()` and `ldap_parse_sasl_bind_result()`, or `ldap_sasl_bind_s()`
Specify the function used to get authentication information when following referrals	`ldap_set_rebind_proc()`

Performing LDAP Operations

Call the following functions to perform LDAP operations on a server.

Table 18.3 Functions for performing LDAP operations

To do this: Call this function:
Add a new entry to the directory
ldap_add_ext() or ldap_add_ext_s()

Modify an entry in the directory
ldap_modify_ext() or ldap_modify_ext_s()

Delete an entry from the directory
ldap_delete_ext() or ldap_delete_ext_s()

Rename an entry in the directory
ldap_rename() or ldap_rename_s()

Search the directory
ldap_search_ext() or ldap_search_ext_s()

Compare entries in the directory
ldap_compare_ext() or ldap_compare_ext_s()

Perform an LDAP v3 extended operation
ldap_extended_operation() or ldap_extended_operation_s()

Check the results of an asynchronous operation
ldap_result()

Parse the results of an LDAP v3 extended operation
ldap_parse_extended_result()

Free the results from memory
ldap_msgfree()

Cancel an asynchronous operation
ldap_abandon_ext()

To do this:	Call this function:
Add a new entry to the directory	`ldap_add_ext()` or `ldap_add_ext_s()`
Modify an entry in the directory	`ldap_modify_ext()` or `ldap_modify_ext_s()`
Delete an entry from the directory	`ldap_delete_ext()` or `ldap_delete_ext_s()`
Rename an entry in the directory	`ldap_rename()` or `ldap_rename_s()`
Search the directory	`ldap_search_ext()` or `ldap_search_ext_s()`
Compare entries in the directory	`ldap_compare_ext()` or `ldap_compare_ext_s()`
Perform an LDAP v3 extended operation	`ldap_extended_operation()` or `ldap_extended_operation_s()`
Check the results of an asynchronous operation	`ldap_result()`
Parse the results of an LDAP v3 extended operation	`ldap_parse_extended_result()`
Free the results from memory	`ldap_msgfree()`
Cancel an asynchronous operation	`ldap_abandon_ext()`

Getting Search Results

Call the following functions to retrieve search results.

To do this:	Call this function:
Get the first message (an entry or search reference) in a chain of search results	`ldap_first_message()`
Get the next message (an entry or search reference) in a chain of search results	`ldap_next_message()`
Count the number of messages (entries and search references) in a chain of search results	`ldap_count_messages()`
Get the first entry in a chain of search results	`ldap_first_entry()`
Get the next entry in a chain of search results	`ldap_next_entry()`
Count the number of entries in a chain of search results	`ldap_count_entries()`
Get the first search reference in a chain of search results	`ldap_first_reference()`
Get the next search reference in a chain of search results	`ldap_next_reference()`
Count the number of search references in a chain of search results	`ldap_count_references()`
Get the distinguished name for an entry	`ldap_get_dn()`
Get the name of the first attribute in an entry	`ldap_first_attribute()`
Get the name of the next attribute in an entry	`ldap_next_attribute()`
Get the string values of an attribute	`ldap_get_values()`
Get the binary values of an attribute	`ldap_get_values_len()`
Count the string values of an attribute	`ldap_count_values()`
Count the binary values of an attribute	`ldap_count_values_len()`
Get the string values of the specified language subtype of an attribute	`ldap_get_lang_values()`
Get the binary values of the specified language subtype of an attribute	`ldap_get_lang_values_len()`
Free the memory allocated for the string values of an attribute	`ldap_value_free()`
Free the memory allocated for the binary values of an attribute	`ldap_value_free_len()`

Sorting Search Results

Call the following functions to sort search results.

Table 18.5 Functions for sorting search results

To do this: Call this function:
Have your client sort entries by distinguished name or by a single attribute
ldap_sort_entries()

Have your client sort entries by multiple attributes
ldap_multisort_entries()

Request that the server sort the search results before sending them to your client
ldap_create_sort_keylist(), ldap_create_sort_control(), ldap_parse_sort_control()

Sort the values of an attribute
ldap_sort_values()

A case-insensitive comparison function that you can pass to ldap_sort_values()
ldap_sort_strcasecmp()

To do this:	Call this function:
Have your client sort entries by distinguished name or by a single attribute	`ldap_sort_entries()`
Have your client sort entries by multiple attributes	`ldap_multisort_entries()`
Request that the server sort the search results before sending them to your client	`ldap_create_sort_keylist()`, `ldap_create_sort_control()`, `ldap_parse_sort_control()`
Sort the values of an attribute	`ldap_sort_values()`
A case-insensitive comparison function that you can pass to ldap_sort_values()	`ldap_sort_strcasecmp()`

Working with Search Filters

Call the following functions to initialize, retrieve, and build filters.

Table 18.6 Functions for working with search filters

To do this: Call this function:
Read a filter configuration file into memory
ldap_init_getfilter()

Read a filter configuration from a buffer
ldap_init_getfilter_buf()

Specify the prefix and suffix to be added to all filters retrieved from the filter configuration
ldap_set_filter_additions()

Retrieve the first matching filter from the filter configuration
ldap_getfirstfilter()

Retrieve the next matching filter from the filter configuration
ldap_getnextfilter()

Free the filter configuration from memory
ldap_getfilter_free()

Build a filter
ldap_create_filter()

To do this:	Call this function:
Read a filter configuration file into memory	`ldap_init_getfilter()`
Read a filter configuration from a buffer	`ldap_init_getfilter_buf()`
Specify the prefix and suffix to be added to all filters retrieved from the filter configuration	`ldap_set_filter_additions()`
Retrieve the first matching filter from the filter configuration	`ldap_getfirstfilter()`
Retrieve the next matching filter from the filter configuration	`ldap_getnextfilter()`
Free the filter configuration from memory	`ldap_getfilter_free()`
Build a filter	`ldap_create_filter()`

Working with Distinguished Names

Call the following functions to retrieve a distinguished name from an entry and to split a distinguished name into its component parts.

Table 18.7 Functions for working with distinguished names

To do this: Call this function:
Get the distinguished name for an entry
ldap_get_dn()

Split up a distinguished name into its components
ldap_explode_dn()

Split up a relative distinguished name into its components
ldap_explode_rdn()

To do this:	Call this function:
Get the distinguished name for an entry	`ldap_get_dn()`
Split up a distinguished name into its components	`ldap_explode_dn()`
Split up a relative distinguished name into its components	`ldap_explode_rdn()`

Working with LDAP v3 Controls

Call the following functions to work with LDAP v3 controls.

Table 18.8 Functions for working with LDAP v3 controls

To do this: Call this function:
Create a "persistent search" control to track changes in directory entries
ldap_create_persistentsearch_control()

Create a "sorting" control to return sorted search results from the LDAP server
ldap_create_sort_keylist(), ldap_create_sort_control()

Pass LDAP controls to the server
ldap_add_ext(), ldap_add_ext_s(), ldap_compare_ext(), ldap_compare_ext_s(), ldap_delete_ext(), ldap_delete_ext_s(), ldap_extended_operation(), ldap_extended_operation_s(), ldap_modify_ext(), ldap_modify_ext_s(), ldap_rename(), ldap_rename_s(), ldap_sasl_bind(), ldap_sasl_bind_s(), ldap_search_ext(), ldap_search_ext_s(), ldap_abandon_ext()

Parse LDAP server controls from results sent from the server
ldap_parse_result()

Parse an "entry change notification" control from an entry and retrieve information from the control
ldap_get_entry_controls(), ldap_parse_entrychange_control()

Parse "sorting" controls from results sent from the server
ldap_parse_sort_control()

Free the memory allocated for an LDAPControl structure
ldap_control_free()

Free the memory allocated for an array of LDAPControl structures
ldap_controls_free()

To do this:	Call this function:
Create a "persistent search" control to track changes in directory entries	`ldap_create_persistentsearch_control()`
Create a "sorting" control to return sorted search results from the LDAP server	`ldap_create_sort_keylist()`, `ldap_create_sort_control()`
Pass LDAP controls to the server	`ldap_add_ext()`, `ldap_add_ext_s()`, `ldap_compare_ext()`, `ldap_compare_ext_s()`, `ldap_delete_ext()`, `ldap_delete_ext_s()`, `ldap_extended_operation()`, `ldap_extended_operation_s()`, `ldap_modify_ext()`, `ldap_modify_ext_s()`, `ldap_rename()`, `ldap_rename_s()`, `ldap_sasl_bind()`, `ldap_sasl_bind_s()`, `ldap_search_ext()`, `ldap_search_ext_s()`, `ldap_abandon_ext()`
Parse LDAP server controls from results sent from the server	`ldap_parse_result()`
Parse an "entry change notification" control from an entry and retrieve information from the control	`ldap_get_entry_controls()`, `ldap_parse_entrychange_control()`
Parse "sorting" controls from results sent from the server	`ldap_parse_sort_control()`
Free the memory allocated for an `LDAPControl` structure	`ldap_control_free()`
Free the memory allocated for an array of `LDAPControl` structures	`ldap_controls_free()`

Working with LDAP URLs

Call the following functions to interpret LDAP URLs.

Table 18.9 Functions for working with LDAP URLs

To do this: Call this function:
Determine if a URL is an LDAP URL
ldap_is_ldap_url()

Split up an LDAP URL into its components
ldap_url_parse()

Perform the search specified by an LDAP URL
ldap_url_search(), ldap_url_search_s(), or ldap_url_search_st()

Free the memory allocated for a parsed URL
ldap_free_urldesc()

To do this:	Call this function:
Determine if a URL is an LDAP URL	`ldap_is_ldap_url()`
Split up an LDAP URL into its components	`ldap_url_parse()`
Perform the search specified by an LDAP URL	`ldap_url_search()`, `ldap_url_search_s()`, or `ldap_url_search_st()`
Free the memory allocated for a parsed URL	`ldap_free_urldesc()`

Getting the Attribute Values for a Particular Language

Call the following functions to get the values from a particular language subtype in an attribute.

Table 18.10 Functions for getting the values in an attribute's subtype

To do this: Call this function:
Get an attribute's value in a particular language
ldap_get_lang_values() or ldap_get_lang_values_len()

To do this:	Call this function:
Get an attribute's value in a particular language	`ldap_get_lang_values()` or `ldap_get_lang_values_len()`

Handling Errors

Call the following functions to handle errors returned by the LDAP API functions.

Table 18.11 Functions for handling errors

To do this: Call this function:
Get the error code resulting from an asynchronous LDAP operation
ldap_parse_result()

Get information about the last error that occurred
ldap_get_lderrno()

Set information about an error
ldap_set_lderrno()

Get the error message for a specific error code
ldap_err2string()

Print out the error message for the last error that occurred
ldap_perror()

To do this:	Call this function:
Get the error code resulting from an asynchronous LDAP operation	`ldap_parse_result()`
Get information about the last error that occurred	`ldap_get_lderrno()`
Set information about an error	`ldap_set_lderrno()`
Get the error message for a specific error code	`ldap_err2string()`
Print out the error message for the last error that occurred	`ldap_perror()`

Freeing Memory

Call the following functions to free memory allocated by the LDAP API functions.

To do this:	Call this function:
Free memory allocated by an LDAP API function call	`ldap_memfree()`
Free the structures allocated for adding or modifying entries in the directory.	`ldap_mods_free()`
Free the memory allocated for search results or other LDAP operation results	`ldap_msgfree()`
Free the memory allocated for the string values of an attribute	`ldap_value_free()`
Free the memory allocated for the binary values of an attribute (an array of `berval` structures)	`ldap_value_free_len()`
Free the memory allocated for a `berval` structures	`ber_bvfree()`
Free the filter configuration from memory	`ldap_getfilter_free()`
Free the memory allocated for a parsed URL	`ldap_free_urldesc()`
Free the memory allocated for a `BerElement` structure	`ldap_ber_free()`
Free the memory allocated for an `LDAPControl` structure	`ldap_control_free()`
Free the memory allocated for an array of `LDAPControl` structures	`ldap_controls_free()`
Free the memory allocated for an array of `LDAPsortkey` structures	`ldap_free_sort_keylist()`