<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="bdane"><title>&DirectorySDKForC; Function Reference</title>
<indexterm>
<primary>functions</primary>
<see>C SDK functions</see></indexterm><indexterm>
<primary>C SDK functions</primary>
</indexterm><highlights>
<para>This chapter contains detailed reference material for each public function
of &DirectorySDKForC;. Each reference gives a description of the function,
and its usage syntax, parameters and return values. In many cases, an example
program is also included. The chapter contains the following sections:</para>
<itemizedlist>
<listitem><para><olink targetptr="bdanf">Typographic Conventions</olink></para>
</listitem>
<listitem><para><olink targetptr="bdang">Function Summary by Task</olink></para>
</listitem>
<listitem><para><olink targetptr="bdanx">Functions Alphabetically</olink></para>
</listitem>
</itemizedlist>
</highlights>
<sect1 id="bdanf"><title>Typographic Conventions</title>
<para>The general purpose of a function is usually given by  its name.  <olink targetptr="function-naming-conventions">Table 21&ndash;1</olink> lists the
naming conventions used when adding suffixes to function names.</para>
<table frame="topbot" id="function-naming-conventions"><title>Function Naming
Conventions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Suffix</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>_ext</literal></para></entry>
<entry>
<para>Identifies extended functions introduced for LDAP v3. These functions
are augmented through additional parameters, as compared to the functions
they replace. As LDAP v3 has become widely adopted, it is recommended you
use extended functions whenever possible in your new applications.</para>
</entry>
</row>
<row>
<entry>
<para><literal>_s</literal></para></entry>
<entry>
<para>Identifies the synchronous form of functions. A synchronous function
will not return until it receives a response from the server, thereby blocking
the caller. Similar function names without this suffix are asynchronous, allowing
the caller to perform other operations while waiting for a result.</para>
<para>The synchronous and asynchronous forms exist only for functions which
involve possible delays due to communication with the LDAP server. Functions
which do not involve communication do not use this suffix.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="bdang"><title>Function Summary by Task</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>summary of</tertiary>
</indexterm><indexterm>
<primary>functions</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>In the following sections the functions of &DirectorySDKForC; are
grouped into task categories.</para>
<sect2 id="bdanh"><title>Working with Basic Encoding Rules</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for BER</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="ber-encoding-functions">Table
21&ndash;2</olink> may be used to encode and decode with Basic Encoding Rules
(BER). They are often used inside of control and extension values.</para>
<table frame="topbot" id="ber-encoding-functions"><title>Functions to Encode
and Decode BER</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdany">ber_alloc</olink>, <olink targetptr="bdanz">ber_alloc_t
</olink>, <olink targetptr="bdapl">ber_sockbuf_alloc</olink>, <olink targetptr="bdapq">ber_special_alloc</olink></para></entry>
<entry>
<para>Allocate new BER elements.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaoa">ber_bvecfree</olink>, <olink targetptr="bdaoc">ber_bvfree
</olink>, <olink targetptr="bdaog">ber_free</olink>, <olink targetptr="bdapm">ber_sockbuf_free
</olink>, <olink targetptr="bdapn">ber_sockbuf_free_data</olink></para></entry>
<entry>
<para>Free allocated memory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaob">ber_bvdup</olink>, <olink targetptr="bdaod">ber_dup
</olink></para></entry>
<entry>
<para>Duplicate BER structures.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaor">ber_init</olink>, <olink targetptr="bdaos">ber_init_w_nullchar
</olink></para></entry>
<entry>
<para>Construct new structures.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaoh">ber_get_boolean</olink>, <olink targetptr="bdaoi">
ber_get_int</olink>, <olink targetptr="bdaoj">ber_get_next</olink>, <olink targetptr="bdaok">ber_get_next_buffer</olink>, <olink targetptr="bdaol">ber_get_next_buffer_ext
</olink>, <olink targetptr="bdaom">ber_get_null</olink>, <olink targetptr="bdaon">
ber_get_option</olink>, <olink targetptr="bdaoo">ber_get_stringa</olink>, <olink targetptr="bdaop">ber_get_stringal</olink>, <olink targetptr="bdaoq">ber_get_stringb
</olink></para></entry>
<entry>
<para>Retrieve miscellaneous information.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaow">ber_put_bitstring</olink>, <olink targetptr="bdaox">ber_put_boolean</olink>, <olink targetptr="bdaoy">ber_put_enum</olink>, <olink targetptr="bdaoz">ber_put_int</olink>, <olink targetptr="bdapa">ber_put_null</olink>, <olink targetptr="bdapb">ber_put_ostring</olink>, <olink targetptr="bdapc">ber_put_seq</olink>, <olink targetptr="bdapd">ber_put_set</olink>, <olink targetptr="bdape">ber_put_string</olink></para>
</entry>
<entry>
<para>Write miscellaneous information.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaoe">ber_first_element</olink>, <olink targetptr="bdaot">ber_next_element</olink>, <olink targetptr="bdaou">ber_peek_tag
</olink>, <olink targetptr="bdapk">ber_skip_tag</olink></para></entry>
<entry>
<para>Target specific elements and tags.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdapi">ber_set_option</olink>, <olink targetptr="bdapj">ber_set_string_translators
</olink></para></entry>
<entry>
<para>Set session parameters.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaof">ber_flatten</olink>, <olink targetptr="bdaov">ber_printf
</olink>, <olink targetptr="bdapf">ber_read</olink>, <olink targetptr="bdapg">ber_reset
</olink>, <olink targetptr="bdaph">ber_scanf</olink>, <olink targetptr="bdapo">ber_sockbuf_get_option
</olink>, <olink targetptr="bdapp">ber_sockbuf_set_option</olink>, <olink targetptr="bdapt">ber_start_seq</olink>, <olink targetptr="bdapt">ber_start_seq</olink>, <olink targetptr="bdapu">ber_start_set</olink>, <olink targetptr="bdapv">ber_svecfree</olink>, <olink targetptr="bdapw">ber_write</olink></para></entry>
<entry>
<para>Miscellaneous functions.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdani"><title>Managing LDAP Sessions</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for LDAP sessions</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="manage-session-functions">Table
21&ndash;3</olink> manage the different phases of an LDAP session: initialization,
configuration, authentication (binding) and termination (unbinding).</para>
<table frame="topbot" id="manage-session-functions"><title>Functions to Manage
an LDAP Session</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6)</para></entry>
<entry>
<para>Initializes an LDAP session.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavs">ldapssl_init</olink></para></entry>
<entry>
<para>Initializes an LDAP session over SSL.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavu">ldapssl_pkcs_init</olink></para></entry>
<entry>
<para>Initializes a thread-safe session over SSL.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdass">ldap_get_option</olink>, <olink targetptr="bdavg">
ldap_set_option</olink></para></entry>
<entry>
<para>Read and writes the current preference settings for a session.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdati">ldap_memcache_init</olink>, <olink targetptr="bdatj">ldap_memcache_set</olink>, <olink targetptr="bdath">ldap_memcache_get
</olink>, <olink targetptr="bdatk">ldap_memcache_update</olink>, <olink targetptr="bdatg">ldap_memcache_flush</olink>, <olink targetptr="bdatf">ldap_memcache_destroy
</olink></para></entry>
<entry>
<para>Creates a memory cache and uses it for search results from this session.
Manages the data in the cache and frees the memory when the cache is no longer
needed. The in-memory cache for search results is an extension to the API.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawj">ldap_unbind_ext</olink></para></entry>
<entry>
<para>Ends an LDAP session and frees the associated data structures.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanj"><title>Performing LDAP Operations</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for LDAP operations</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="ldapops-functions">Table 21&ndash;4
</olink> perform LDAP operations on a server and retrieve the results.</para>
<table frame="topbot" id="ldapops-functions"><title>Functions to Perform Operations
on LDAP Server</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaqa">ldap_add_ext</olink> or <olink targetptr="bdaqb">ldap_add_ext_s
</olink></para></entry>
<entry>
<para>Adds a new entry to the directory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatn">ldap_modify_ext</olink> or <olink targetptr="bdato">ldap_modify_ext_s</olink></para></entry>
<entry>
<para>Modifies an entry in the directory</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdari">ldap_delete_ext</olink> or <olink targetptr="bdarj">ldap_delete_ext_s</olink></para></entry>
<entry>
<para>Deletes an entry from the directory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaus">ldap_rename</olink> or<olink targetptr="bdaut">ldap_rename_s
</olink></para></entry>
<entry>
<para>Renames or moves one or more entries.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauz">ldap_search_ext</olink> or <olink targetptr="bdava">ldap_search_ext_s</olink></para></entry>
<entry>
<para>Searches the directory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqp">ldap_compare_ext</olink> or <olink targetptr="bdaqq">ldap_compare_ext_s</olink></para></entry>
<entry>
<para>Compares a value with the values of an entry's attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauu">ldap_result</olink></para></entry>
<entry>
<para>Checks the results of an asynchronous operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></entry>
<entry>
<para>Cancels an asynchronous operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaru">ldap_extended_operation</olink> or <olink targetptr="bdarv">ldap_extended_operation_s</olink></para></entry>
<entry>
<para>Performs an LDAP v3 extended operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaul">ldap_parse_extended_result</olink></para></entry>
<entry>
<para>Parses the results of an LDAP v3 extended operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
<entry>
<para>Frees the memory used by the data structure for the results.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavi">ldap_simple_bind</olink> or <olink targetptr="bdavj">ldap_simple_bind_s</olink></para></entry>
<entry>
<para>Authenticates to an LDAP server using a password.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauw">ldap_sasl_bind</olink> and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> or <olink targetptr="bdaux">
ldap_sasl_bind_s</olink></para></entry>
<entry>
<para>Authenticates to an LDAP server using a SASL mechanism.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavh">ldap_set_rebind_proc</olink></para></entry>
<entry>
<para>Specifies the function used to get authentication information when following
referrals.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdank"><title>Processing Search Results</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for search results processing</tertiary>
</indexterm>
<para>Search results are given as a chain of <olink targetptr="bdaly">LDAPMessage
</olink> structures which can contain both entry messages and search reference
messages. The functions listed in <olink targetptr="search-functions">Table
21&ndash;5</olink> retrieve the results of a search operation and process
the data structures which are returned.</para>
<table frame="topbot" id="search-functions"><title>Functions to Process Search
Results</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdarz">ldap_first_message</olink></para></entry>
<entry>
<para>Gets the first message (an entry or search reference) in a chain of
search results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaud">ldap_next_message</olink></para></entry>
<entry>
<para>Gets the next message (an entry or search reference) in a chain of search
results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqv">ldap_count_messages</olink></para></entry>
<entry>
<para>Counts the number of messages (entries and search references) in a chain
of search results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatw">ldap_msgid</olink></para></entry>
<entry>
<para>Gets the ID number of a message structure containing part of a result.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatx">ldap_msgtype</olink></para></entry>
<entry>
<para>Determines whether a message structure contains an entry or a search
reference.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
<entry>
<para>Frees the memory allocated for search results or other LDAP operation
results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdary">ldap_first_entry</olink></para></entry>
<entry>
<para>Gets the first entry in a chain of search results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauc">ldap_next_entry</olink></para></entry>
<entry>
<para>Gets the next entry in a chain of search results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqu">ldap_count_entries</olink></para></entry>
<entry>
<para>Counts the number of entries in a chain of search results.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasa">ldap_first_reference</olink></para></entry>
<entry>
<para>Gets the first search reference in a chain of search results.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaue">ldap_next_reference</olink></para></entry>
<entry>
<para>Gets the next search reference in a chain of search results.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqw">ldap_count_references</olink></para></entry>
<entry>
<para>Counts the number of search references in a chain of search results.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaum">ldap_parse_reference</olink></para></entry>
<entry>
<para>Extracts the referral strings from a search reference.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanl"><title>Reading the Contents of an Entry</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for reading entry contents</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="entry-functions">Table 21&ndash;6
</olink> are used to access the contents of an entry returned as a search
result.</para>
<table frame="topbot" id="entry-functions"><title>Functions to Access Contents
of an Entry</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdask">ldap_get_dn</olink></para></entry>
<entry>
<para>Get the DN for an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarr">ldap_explode_dn</olink> <olink targetptr="bdart">ldap_explode_rdn
</olink></para></entry>
<entry>
<para>Split a DN or relative DN into its components.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdars">ldap_explode_dns</olink></para></entry>
<entry>
<para>Takes a DNS-style DN and breaks it up into its components.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatc">ldap_is_dns_dn</olink></para></entry>
<entry>
<para>Determines the style of the DN.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarl">ldap_dn2ufn</olink></para></entry>
<entry>
<para>Removes cryptic type names to make a DN easier to read.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarw">ldap_first_attribute</olink></para></entry>
<entry>
<para>Get the name of the first attribute in an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaua">ldap_next_attribute</olink></para></entry>
<entry>
<para>Get the name of the next attribute in an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdast">ldap_get_values</olink></para></entry>
<entry>
<para>Get the string values of an attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasu">ldap_get_values_len</olink></para></entry>
<entry>
<para>Get the binary values of an attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqx">ldap_count_values</olink></para></entry>
<entry>
<para>Count the string values of an attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqy">ldap_count_values_len</olink></para></entry>
<entry>
<para>Count the binary values of an attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></entry>
<entry>
<para>Free the memory allocated for the string values of an attribute.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxd">ldap_value_free_len</olink></para></entry>
<entry>
<para>Free the memory allocated for the binary values of an attribute.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanm"><title>Sorting Search Results</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for sorting search results</tertiary>
</indexterm>
<para>With the functions listed in <olink targetptr="client-sort-functions">Table
21&ndash;7</olink>, your LDAP client can sort the data structures returned
as search results.</para>
<table frame="topbot" id="client-sort-functions"><title>Client-side Sorting
Functions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdavk">ldap_sort_entries</olink></para></entry>
<entry>
<para>Sorts search results by DN or by a single attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaty">ldap_multisort_entries</olink></para></entry>
<entry>
<para>Sorts search results by multiple attributes</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdate">ldap_keysort_entries</olink></para></entry>
<entry>
<para>Sorts search results using key(s).</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavm">ldap_sort_values</olink></para></entry>
<entry>
<para>Sorts the values of an attribute.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavl">ldap_sort_strcasecmp</olink></para></entry>
<entry>
<para>A case-insensitive comparison function that you can pass to  <olink targetptr="bdavm">ldap_sort_values</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>&cnDirectoryServer; and others also provide server-side sorting through
LDAP v3 controls.</para>
<table frame="topbot" id="server-sort-functions"><title>Server-Side Sorting
Functions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink></para></entry>
<entry>
<para>Define the criteria for sorting entries by attribute values.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></entry>
<entry>
<para>Free the memory for the sort criteria data structure.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdare">ldap_create_sort_control</olink></para></entry>
<entry>
<para>Create the sort control structure needed for server-side sorting.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></entry>
<entry>
<para>Free the memory for the sort control data structure.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaup">ldap_parse_sort_control</olink></para></entry>
<entry>
<para>Analyze the server&rsquo;s response to the sort control.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></entry>
<entry>
<para>Free the memory for the sort control response data structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdann"><title>Working with Search Filters</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for search filters</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="filter-functions">Table 21&ndash;9
</olink> retrieve and build filters using a filter configuration file. Use
this mechanism to create complex filters to pass to the search functions.</para>
<table frame="topbot" id="filter-functions"><title>Functions to Initialize,
Retrieve, and Build Filters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdasw">ldap_init_getfilter</olink></para></entry>
<entry>
<para>Read a filter configuration file into memory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasx">ldap_init_getfilter_buf</olink></para></entry>
<entry>
<para>Read a filter configuration string from a buffer.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasm">ldap_getfilter_free</olink></para></entry>
<entry>
<para>Free the filter configuration data structure from memory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavd">ldap_set_filter_additions</olink></para></entry>
<entry>
<para>Specify the prefix and suffix to be added to all filters retrieved from
the filter configuration.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink></para></entry>
<entry>
<para>Retrieve the first matching filter from the filter configuration.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasr">ldap_getnextfilter</olink></para></entry>
<entry>
<para>Retrieve the next matching filter from the filter configuration.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqz">ldap_create_filter</olink></para></entry>
<entry>
<para>Build a filter without using the filter configuration file mechanism.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdano"><title>Using LDAP v3 Controls</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for LDAP v3 controls</tertiary>
</indexterm>
<para>&cnDirectoryServer; and others also provide additional functionality
through LDAP v3 controls. The functions listed in <olink targetptr="controls-functions">Table 21&ndash;10</olink> configure LDAP v3
control structures which ask the server to perform advanced operations.</para>
<table frame="topbot" id="controls-functions"><title>Functions to Manage LDAP
v3 Controls</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="ldap-create-authzid-control">ldap_create_authzid_control</olink>, <olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink></para>
</entry>
<entry>
<para>Examine the authorization ID used for the operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdara">ldap_create_persistentsearch_control</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink>, <olink targetptr="bdauk">ldap_parse_entrychange_control
</olink></para></entry>
<entry>
<para>Track changes to an entry or a set of entries by setting the persistent
search control and analyzing the entry change control sent by the server.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarc">ldap_create_proxiedauth_control</olink></para>
</entry>
<entry>
<para>Define a proxy authorization control to perform an operation under a
different bind DN</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="ldap-create-pwdpolicy-control">ldap_create_pwdpolicy_control
</olink>, <olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
</olink></para></entry>
<entry>
<para>Examine password policy information for an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>, <olink targetptr="bdasg">ldap_free_sort_keylist</olink>, <olink targetptr="bdare">ldap_create_sort_control
</olink>, <olink targetptr="bdaup">ldap_parse_sort_control</olink></para>
</entry>
<entry>
<para>Define and send criteria for server-side sorting of search results and
check the server&rsquo;s response</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
</olink>, <olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
</olink></para></entry>
<entry>
<para>Examine account availability information for an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarg">ldap_create_virtuallist_control</olink>, <olink targetptr="bdauq">ldap_parse_virtuallist_control</olink></para></entry>
<entry>
<para>Use in conjunction with server-side sorting to limit and handle the
number of results returned to the client.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaun">ldap_parse_result</olink></para></entry>
<entry>
<para>Parse an LDAP response from the server to extract the result and the
response to the control.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanp"><title>Using Extensions</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for parsing host lists</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="proprietary-extensions">Table
21&ndash;11</olink> are utility functions for parsing space-separated host
lists. This is useful for implementing an extended I/O CONNECT callback function.
</para>
<table frame="topbot" id="proprietary-extensions"><title>Extensions Provided</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>, <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdaxj">ldap_x_hostlist_status
</olink></para></entry>
<entry>
<para>Utility functions for parsing space-separated host lists.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanq"><title>Working with LDAP URLs</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for LDAP URLs</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="ldapurl-functions">Table 21&ndash;12
</olink> interpret LDAP URLs, universal resource locators of the form  <literal>ldap://...
</literal>.</para>
<table frame="topbot" id="ldapurl-functions"><title>Functions to Interpret
LDAP URLs</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdatd">ldap_is_ldap_url</olink></para></entry>
<entry>
<para>Determine if a URL is an LDAP URL.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></entry>
<entry>
<para>Split up an LDAP URL into its components.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawm">ldap_url_search</olink>, <olink targetptr="bdawn">
ldap_url_search_s</olink>, <olink targetptr="bdawo">ldap_url_search_st</olink></para>
</entry>
<entry>
<para>Perform the search specified by an LDAP URL.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></entry>
<entry>
<para>Free the memory allocated for a parsed URL.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanr"><title>Working with UTF-8 Encoding</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for UTF-8 encoding</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="utf8-functions">Table 21&ndash;13
</olink> work with strings and characters that use UTF-8 encoding.</para>
<table frame="topbot" id="utf8-functions"><title>Functions to Handle UTF-8
Encoding</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaww">ldap_utf8len</olink></para></entry>
<entry>
<para>Function to determine byte length.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawx">ldap_utf8next</olink></para></entry>
<entry>
<para>Function to get next character.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawy">ldap_utf8prev</olink></para></entry>
<entry>
<para>Function to get previous character.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawq">ldap_utf8copy</olink></para></entry>
<entry>
<para>Function to copy a character to a destination.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawp">ldap_utf8characters</olink></para></entry>
<entry>
<para>Function to return the number of characters.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawr">ldap_utf8getcc</olink></para></entry>
<entry>
<para>Function moves the pointer to the next character following a UCS-4 character.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawz">ldap_utf8strtok_r</olink></para></entry>
<entry>
<para>Function moves the pointer to the next character following a UCS-4 character.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaws">ldap_utf8isalnum</olink>, <olink targetptr="bdawt">
ldap_utf8isalpha</olink>, <olink targetptr="bdawu">ldap_utf8isdigit</olink>, <olink targetptr="bdaww">ldap_utf8len</olink>, <olink targetptr="bdawv">ldap_utf8isspace
</olink></para></entry>
<entry>
<para>Functions to determine characteristics of the character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdans"><title>Handling Errors</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for error handling</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="error-functions">Table 21&ndash;14
</olink> handle errors returned by the functions.  <olink targetptr="bdaxx">Chapter&nbsp;22,
Directory SDK for C Result Codes</olink> lists all of the error and status
codes used in the &DirectorySDKForC;. You can also find details about possible
errors in the reference section for each function.</para>
<table frame="topbot" id="error-functions"><title>Functions for Error Handling</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaun">ldap_parse_result</olink></para></entry>
<entry>
<para>Get the error code resulting from an asynchronous LDAP operation.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasq">ldap_get_lderrno</olink></para></entry>
<entry>
<para>Get information about the last error that occurred.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavf">ldap_set_lderrno</olink></para></entry>
<entry>
<para>Set information about an error.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarq">ldap_err2string</olink></para></entry>
<entry>
<para>Get the error message for a specific error code.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdavr">ldapssl_err2string</olink></para></entry>
<entry>
<para>Get the error message for a specific SSL error code.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdant"><title>Managing Memory</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for memory management</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="free-functions">Table 21&ndash;15
</olink> free memory allocated by the &DirectorySDKForC; functions.</para>
<table frame="topbot" id="free-functions"><title>Functions to Free Memory</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></entry>
<entry>
<para>Free the memory allocated for a <olink targetptr="bdakg">berval</olink> structure.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaog">ber_free</olink></para></entry>
<entry>
<para>Free the memory of a <olink targetptr="bdakh">BerElement</olink> structure.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></entry>
<entry>
<para>Free the memory of an <olink targetptr="bdala">LDAPControl</olink> structure.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></entry>
<entry>
<para>Free an array of <olink targetptr="bdala">LDAPControl</olink> structures.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdase">ldap_free_friendlymap</olink></para></entry>
<entry>
<para>Free the memory of a <olink targetptr="bdaki">FriendlyMap</olink> structure
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></entry>
<entry>
<para>Free an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></entry>
<entry>
<para>Free the memory of an <olink targetptr="bdams">LDAPURLDesc</olink> structure
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdasm">ldap_getfilter_free</olink></para></entry>
<entry>
<para>Free the memory of an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatl">ldap_memfree</olink></para></entry>
<entry>
<para>General function for freeing memory of any other data structure</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatu">ldap_mods_free</olink></para></entry>
<entry>
<para>Free an array of <olink targetptr="bdalz">LDAPMod</olink> structure.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
<entry>
<para>Free the memory of an <olink targetptr="bdaly">LDAPMessage</olink> structure.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></entry>
<entry>
<para>Free the memory allocated for the string values of an attribute.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxd">ldap_value_free_len</olink></para></entry>
<entry>
<para>Free the memory allocated for the binary values of an attribute (an
array of <olink targetptr="bdakg">berval</olink> structures)</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>You may also manage memory directly with the functions in  <olink targetptr="mem-mngt-functions">Table 21&ndash;16</olink>.</para>
<table frame="topbot" id="mem-mngt-functions"><title>Functions to Directly
Manage Memory</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaxl">ldap_x_malloc</olink></para></entry>
<entry>
<para>Allocates memory.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxf">ldap_x_calloc</olink></para></entry>
<entry>
<para>Allocates memory for an array of elements.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxm">ldap_x_realloc</olink></para></entry>
<entry>
<para>Changes the size of a memory block.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxg">ldap_x_free</olink></para></entry>
<entry>
<para>Frees a block of memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanu"><title>Working with <acronym>NSPR</acronym></title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>for NSPR</tertiary>
</indexterm>
<para>The functions listed in <olink targetptr="nspr-functions">Table 21&ndash;17
</olink> tie <literal>libldap</literal> into Netscape Portable Runtime, <acronym>
NSPR</acronym>.</para>
<table frame="topbot" id="nspr-functions"><title>Functions to Work with <acronym>
NSPR</acronym></title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaxn">prldap_get_default_socket_info</olink></para>
</entry>
<entry>
<para>Gets default socket information.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxo">prldap_get_session_info</olink></para></entry>
<entry>
<para>Gets application-specific data.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxp">prldap_get_session_option</olink></para></entry>
<entry>
<para>Gets a session option specific to the <literal>prldap</literal> layer.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></entry>
<entry>
<para>Gets socket information.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxr">prldap_init</olink></para></entry>
<entry>
<para>Creates a new <acronym>NSPR</acronym> session handle.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxs">prldap_install_routines</olink></para></entry>
<entry>
<para>Installs <acronym>NSPR</acronym> functions for use with LDAP handle.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxt">prldap_set_default_socket_info</olink></para>
</entry>
<entry>
<para>Sets default socket information.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxu">prldap_set_session_info</olink></para></entry>
<entry>
<para>Sets application-specific data.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxv">prldap_set_session_option</olink></para></entry>
<entry>
<para>Sets a session option specific to the <literal>prldap</literal> layer.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxw">prldap_set_socket_info</olink></para></entry>
<entry>
<para>Sets socket information.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanv"><title>Deprecated and Outdated Functions</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>deprecated</tertiary>
</indexterm>
<para>The functions listed in first column of <olink targetptr="deprecated-functions">Table 21&ndash;18</olink> should no longer
be used; they have been superseded by the newer functions listed in the second
column. Deprecated functions are those being dropped from the standard or
from extensions to &DirectorySDKForC;. Outdated functions are those which
are not officially deprecated but which have newer, extended functions for
performing the same operation.</para>
<note><para>Deprecated functions are not guaranteed to be implemented in future
versions of the API. However, all of these functions are still implemented
in this version for backwards compatibility. For maintenance reasons, they
have often been implemented to call the newer function which performs the
same task.</para></note>
<table frame="topbot" id="deprecated-functions"><title>Deprecated Functions
and Their Replacements</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Deprecated Function</para></entry>
<entry>
<para>Replacement</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdaqd">ldap_ber_free</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdaog">ber_free</olink>.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqe">ldap_bind</olink>, <olink targetptr="bdaqf">ldap_bind_s
</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdavi">ldap_simple_bind</olink> and <olink targetptr="bdavj">ldap_simple_bind_s</olink> respectively.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqg">ldap_build_filter</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdaqz">ldap_create_filter</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqh">ldap_cache_flush</olink></para></entry>
<entry>
<para>Replaced by <function>ldap_memcache_*</function> functions.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqi">ldap_charray_add</olink>, <olink targetptr="bdaqj">
ldap_charray_dup</olink>, <olink targetptr="bdaqk">ldap_charray_free</olink>, <olink targetptr="bdaql">ldap_charray_inlist</olink>, <olink targetptr="bdaqm">ldap_charray_merge
</olink>, <olink targetptr="bdaqn">ldap_charray_position</olink>, <olink targetptr="bdavy">ldap_str2charray</olink></para></entry>
<entry>
<para>None documented to replace these character array functions.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdard">ldap_create_proxyauth_control</olink></para>
</entry>
<entry>
<para>Replaced by <olink targetptr="bdarb">ldap_create_geteffectiveRights_control
</olink>.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaso">ldap_get_lang_values</olink>, <olink targetptr="bdasp">ldap_get_lang_values_len</olink></para></entry>
<entry>
<para>Rarely used, no replacement.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatq">ldap_modrdn</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdats">ldap_modrdn2</olink>, itself outdated
by <olink targetptr="bdaus">ldap_rename</olink>.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatr">ldap_modrdn_s</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdatt">ldap_modrdn2_s</olink>, itself
outdated by <olink targetptr="bdaut">ldap_rename_s</olink>.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauj">ldap_open</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdasv">ldap_init</olink> and one of the
bind functions.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauv">ldap_result2error</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdave">ldap_setfilteraffixes</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdavd">ldap_set_filter_additions</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawb">ldap_ufn_search_c</olink>, <olink targetptr="bdawc">ldap_ufn_search_ct</olink>, <olink targetptr="bdawd">ldap_ufn_search_s
</olink>, <olink targetptr="bdawe">ldap_ufn_setfilter</olink>, <olink targetptr="bdawf">ldap_ufn_setprefix</olink>, <olink targetptr="bdawg">ldap_ufn_timeout
</olink></para></entry>
<entry>
<para>None documented to replace these user-friendly search functions.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaxe">ldap_version</olink></para></entry>
<entry>
<para>Replaced by <olink targetptr="bdass">ldap_get_option</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdanw"><title>Outdated Standard Functions and Equivalents</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>outdated</tertiary>
</indexterm>
<para>Many LDAP v2 functions are outdated now that LDAP v3 has been widely
adopted. <olink targetptr="outdated-functions">Table 21&ndash;19</olink> lists
both the outdated function and its new equivalent. Although LDAP v2 functions
remain in the standard specification, you should use the LDAP v3 functions
in any new client applications. Again, for maintenance reasons, the outdated
functions have often been implemented to call the newer function.</para>
<table frame="topbot" id="outdated-functions"><title>Outdated LDAP v2 Functions
and New Equivalents</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>LDAP v2 Functions</para></entry>
<entry>
<para>LDAP v3 Equivalent</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdapx">ldap_abandon</olink></para></entry>
<entry>
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdapz">ldap_add</olink>, <olink targetptr="bdaqc">ldap_add_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqb">ldap_add_ext_s
</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaqo">ldap_compare</olink>, <olink targetptr="bdaqr">ldap_compare_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdaqp">ldap_compare_ext</olink>, <olink targetptr="bdaqq">
ldap_compare_ext_s</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdarh">ldap_delete</olink>, <olink targetptr="bdark">ldap_delete_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdari">ldap_delete_ext</olink>, <olink targetptr="bdarj">
ldap_delete_ext_s</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatm">ldap_modify</olink>, <olink targetptr="bdatp">ldap_modify_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdatn">ldap_modify_ext</olink>, <olink targetptr="bdato">
ldap_modify_ext_s</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdats">ldap_modrdn2</olink>, <olink targetptr="bdatt">ldap_modrdn2_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdaut">ldap_rename_s
</olink></para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavb">ldap_search_s
</olink>, <olink targetptr="bdavc">ldap_search_st</olink></para></entry>
<entry>
<para><olink targetptr="bdauz">ldap_search_ext</olink>, <olink targetptr="bdava">
ldap_search_ext_s</olink>, <olink targetptr="bdava">ldap_search_ext_s</olink> -
use <parameter>timeout</parameter> argument</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s
</olink></para></entry>
<entry>
<para><olink targetptr="bdawj">ldap_unbind_ext</olink> replaces both forms
which are identical besides the suffix.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
<sect1 id="bdanx"><title>Functions Alphabetically</title>
<indexterm>
<primary>C SDK</primary>
<secondary>functions</secondary>
<tertiary>alphabetically</tertiary>
</indexterm><indexterm>
<primary>functions</primary>
<secondary>C SDK</secondary>
<seealso>C SDK, functions</seealso></indexterm>
<sect2 id="bdany"><title><function>ber_alloc</function></title>
<para>The <function>ber_alloc</function> function is used to allocate a new
Basic Encoding Rules (BER) <olink targetptr="bdakh">BerElement</olink> structure.
</para>
<sect3 id="gaqrr"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
BerElement* ber_alloc( void );</programlisting>
</sect3>
<sect3 id="gaqqn"><title>Parameters</title>
<para>This function has no parameters.</para></sect3>
<sect3 id="gaqri"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to the newly allocated  <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqrc"><title>Description</title>
<para><function>ber_alloc</function> is used to allocate a new  <olink targetptr="bdakh">BerElement</olink> structure for encoding data with the
BER.</para></sect3>
<sect3 id="gaqrf"><title>See Also</title>
<para><olink targetptr="bdaov">ber_printf</olink>, <olink targetptr="bdakh">BerElement
</olink></para></sect3>
</sect2>
<sect2 id="bdanz"><title><function>ber_alloc_t</function></title>
<para>The <function>ber_alloc_t</function> function constructs and returns
a <olink targetptr="bdakh">BerElement</olink> structure.</para>
<sect3 id="gaqqz"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
BerElement* ber_alloc_t( int options );</programlisting>
</sect3>
<sect3 id="gaqrx"><title>Parameters</title>
<table frame="topbot" id="gaqqy"><title><function>ber_alloc_t</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>options</literal></para></entry>
<entry>
<para>Contains bitwise OR of options to be used when generating the encoding
of the <olink targetptr="bdakh">BerElement</olink>. One option is defined
and must always be supplied:</para>
<para><literal>#define LBER_USE_DER 0x01</literal></para>
<para>When this option is present, lengths will always be encoded in the minimum
number of octets. This option does not cause values of sets and sequences
to be rearranged in tag and byte order, so these functions are not suitable
for generating DER output as defined in X.509 and X.680.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqry"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to the newly allocated  <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqru"><title>Description</title>
<para>This function is the same as <olink targetptr="bdany">ber_alloc</olink> except
it has an option.</para></sect3>
<sect3 id="gaqrd"><title>See Also</title>
<para><olink targetptr="bdaov">ber_printf</olink>, <olink targetptr="bdakh">BerElement
</olink></para></sect3>
</sect2>
<sect2 id="bdaoa"><title><function>ber_bvecfree</function></title>
<para>The <function>ber_bvecfree</function> function frees an array of  <olink targetptr="bdakg">berval</olink> structures.</para>
<sect3 id="gaqrk"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_bvecfree( struct berval **bv );</programlisting>
</sect3>
<sect3 id="gaqqd"><title>Parameters</title>
<table frame="topbot" id="gaqrt"><title><function>ber_bvecfree</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>bv</literal></para></entry>
<entry>
<para>Pointer to the array that you want to free from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqqs"><title>Description</title>
<para>Each <olink targetptr="bdakg">berval</olink> in the array is freed using <olink targetptr="bdaoc">ber_bvfree</olink>, and then the array itself is freed.</para>
</sect3>
<sect3 id="gaqrw"><title>See Also</title>
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></sect3>
</sect2>
<sect2 id="bdaob"><title><function>ber_bvdup</function></title>
<para>The <function>ber_bvdup</function> function returns a copy of a  <olink targetptr="bdakg">berval</olink> structure.</para>
<sect3 id="gaqqr"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
berval* ber_bvdup( const struct berval *bv );</programlisting>
</sect3>
<sect3 id="gaqqa"><title>Parameters</title>
<table frame="topbot" id="gaqqu"><title><function>ber_bvdup</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>bv</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure to
be duplicated.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqrm"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to the newly allocated  <olink targetptr="bdakg">berval</olink> structure.</para></listitem>
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqrv"><title>Description</title>
<para>The <function>ber_bvdup</function> function returns a copy of a  <olink targetptr="bdakg">berval</olink> structure. The data referenced in the structure
is also duplicated. The <literal>bv_val</literal> field in the returned <olink targetptr="bdakg">berval</olink>  points to a different area of memory than
the <literal>bv_val</literal> field in the argument <olink targetptr="bdakg">berval
</olink>.</para></sect3>
</sect2>
<sect2 id="bdaoc"><title><function>ber_bvfree</function></title>
<para>The <function>ber_bvfree</function> function frees a  <olink targetptr="bdakg">berval</olink> structure.</para>
<sect3 id="gaqqt"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
 void ber_bvfree( struct berval *bv );</programlisting>
</sect3>
<sect3 id="gaqql"><title>Parameters</title>
<table frame="topbot" id="gaqrn"><title><function>ber_bvfree</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>bv</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure that
you want to free from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqqo"><title>Description</title>
<para>The <function>ber_bvfree</function> function frees a  <olink targetptr="bdakg">berval</olink> structure from memory. Call this function
to free a  <olink targetptr="bdakg">berval</olink> passed back from the <olink targetptr="bdarv">ldap_extended_operation_s</olink> , <olink targetptr="bdaul">ldap_parse_extended_result
</olink>,  <olink targetptr="bdaux">ldap_sasl_bind_s</olink>, or <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink>  functions.</para></sect3>
<sect3 id="gaqrg"><title>See Also</title>
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>,  <olink targetptr="bdaul">ldap_parse_extended_result</olink>, <olink targetptr="bdaux">ldap_sasl_bind_s
</olink> , <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink></para>
</sect3>
</sect2>
<sect2 id="bdaod"><title><function>ber_dup</function></title>
<para>The <function>ber_dup</function> function returns a copy of a  <olink targetptr="bdakh">BerElement</olink> structure.</para>
<sect3 id="gaqqc"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
BerElement* ber_dup( BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqrs"><title>Parameters</title>
<table frame="topbot" id="gaqqw"><title><function>ber_dup</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> to be duplicated.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqqk"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to the newly allocated  <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqre"><title>Description</title>
<para>The <function>ber_dup</function> function returns a copy of a  <olink targetptr="bdakh">BerElement</olink> structure.</para></sect3>
</sect2>
<sect2 id="bdaoe"><title><function>ber_first_element</function></title>
<para>The <function>ber_first_element</function> function is used to return
the tag and length of the first element in a set or sequence.</para>
<sect3 id="gaqqv"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_first_element( BerElement *ber, unsigned long *len,
    char **last );</programlisting>
</sect3>
<sect3 id="gaqrh"><title>Parameters</title>
<table frame="topbot" id="gaqsl"><title><function>ber_first_element</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>Pointer to the address of the unsigned long which returns the length
of the first element.</para></entry>
</row>
<row>
<entry>
<para><literal>last</literal></para></entry>
<entry>
<para>Address of the pointer to return the address of the last byte of the
element.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqtn"><title>Returns</title>
<para><literal>NULL</literal> pointer is returned on error.</para></sect3>
<sect3 id="gaqsu"><title>Description</title>
<para>The <function>ber_first_element</function> function is used to return
the tag and length of the first element in a set or sequence. It also returns
a magic cookie parameter that should be passed to subsequent calls to <olink targetptr="bdaot">ber_next_element</olink> .</para></sect3>
<sect3 id="gaqtm"><title>See Also</title>
<para><olink targetptr="bdaot">ber_next_element</olink></para></sect3>
</sect2>
<sect2 id="bdaof"><title><function>ber_flatten</function></title>
<para>The <function>ber_flatten</function> function allocates a  <olink targetptr="bdakg">berval</olink> structure whose contents are taken from a
source  <olink targetptr="bdakh">BerElement</olink> structure.</para>
<sect3 id="gaqtg"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_flatten( BerElement *ber, struct berval **bvPtr );</programlisting>
</sect3>
<sect3 id="gaqsi"><title>Parameters</title>
<table frame="topbot" id="gaqst"><title><function>ber_flatten</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the source <olink targetptr="bdakh">BerElement</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>bvPtr</literal></para></entry>
<entry>
<para>Pointer to the newly allocated <olink targetptr="bdakg">berval</olink> structure
which must be freed using <olink targetptr="bdaoc">ber_bvfree</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqsa"><title>Returns</title>
<para>Returns <literal>0</literal> on success and <literal>-1</literal> on
error.</para></sect3>
<sect3 id="gaqtc"><title>Description</title>
<para>This function is usually used when encoding LDAP v3 controls or extended
operations values.</para></sect3>
<sect3 id="gaqsd"><title>See Also</title>
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></sect3>
</sect2>
<sect2 id="bdaog"><title><function>ber_free</function></title>
<para>The <function>ber_free</function> function frees a  <olink targetptr="bdakh">BerElement</olink> structure previously allocated with <olink targetptr="bdany">ber_alloc</olink> , <olink targetptr="bdanz">ber_alloc_t</olink>,
 <olink targetptr="bdaor">ber_init</olink>, or the <olink targetptr="bdarw">ldap_first_attribute
</olink>  and <olink targetptr="bdaua">ldap_next_attribute</olink> search
functions.</para>
<sect3 id="gaqsq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
void ber_free( BerElement *ber, int freebuf );</programlisting>
</sect3>
<sect3 id="gaqsp"><title>Parameters</title>
<table frame="topbot" id="gaqtj"><title><function>ber_free</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
that you want to free.</para></entry>
</row>
<row>
<entry>
<para><literal>freebuf</literal></para></entry>
<entry>
<para>Specifies whether or not to free the buffer in the  <olink targetptr="bdakh">BerElement</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqtb"><title>Description</title>
<para>This function frees a <olink targetptr="bdakh">BerElement</olink> structure,
which is used to keep track of the current attribute. When you are done working
with the attributes, you should free this structure from memory, if it still
exists.</para>
<note><para>To retrieve attributes from a search result entry, you need to
call either the <olink targetptr="bdarw">ldap_first_attribute</olink> or  <olink targetptr="bdaua">ldap_next_attribute</olink> function. When freeing structures
allocated by these functions, you should specify <literal>0</literal> for
the <literal>freebuf</literal> argument. Otherwise, it should always be set
to <literal>1</literal>.</para></note>
</sect3>
<sect3 id="gaqsx"><title>Example</title>
<para><olink targetptr="ber-free-example">Example 21&ndash;1</olink> frees
the <olink targetptr="bdakh">BerElement</olink> structure allocated by the <olink targetptr="bdarw">ldap_first_attribute</olink> function.</para>
<example id="ber-free-example"><title>Using <function>ber_free</function></title>
<programlisting>LDAP *ld;
LDAPMessage *a, *e;
BerElement *ber;
...
for ( a = ldap_first_attribute( ld, e, &amp;ber ); a != NULL;
  a =ldap_next_attribute( ld, e, ber ) {
  ...
  /* Retrieve the value of each attribute */
  ...
}

/* Free the BerElement when done */
if ( ber != NULL ) {
  ber_free( ber, 0 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqse"><title>See Also</title>
<para><olink targetptr="bdany">ber_alloc</olink>, <olink targetptr="bdanz">ber_alloc_t
</olink> , <olink targetptr="bdaor">ber_init</olink>, <olink targetptr="bdarw">ldap_first_attribute
</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
</sect2>
<sect2 id="bdaoh"><title><function>ber_get_boolean</function></title>
<para>The <function>ber_get_boolean</function> function is used to read a
boolean value.</para>
<sect3 id="gaqsw"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_boolean( BerElement *ber,
     int *boolval );</programlisting>
</sect3>
<sect3 id="gaqsy"><title>Parameters</title>
<table frame="topbot" id="gaqta"><title><function>ber_get_boolean</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
that contains the boolean.</para></entry>
</row>
<row>
<entry>
<para><literal>boolval</literal></para></entry>
<entry>
<para>Specifies the boolean to read.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqth"><title>Returns</title>
<para>The value is returned on success and <literal>LBER_ERROR</literal> (<literal>
-1</literal>) on failure.</para></sect3>
</sect2>
<sect2 id="bdaoi"><title><function>ber_get_int</function></title>
<para>The <function>ber_get_int</function> function tries to interpret the
next element as an integer, returning the result in <literal>num</literal>.</para>
<sect3 id="gaqtp"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_int( BerElement *ber, int *num );</programlisting>
</sect3>
<sect3 id="gaqsr"><title>Parameters</title>
<table frame="topbot" id="gaqrz"><title><function>ber_get_int</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
that contains the boolean.</para></entry>
</row>
<row>
<entry>
<para><literal>num</literal></para></entry>
<entry>
<para>Pointer to the result.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqsc"><title>Returns</title>
<para>The tag of whatever it finds is returned on success and <literal>LBER_ERROR
</literal>  (<literal>-1</literal>) on failure.</para></sect3>
</sect2>
<sect2 id="bdaoj"><title><function>ber_get_next</function></title>
<para>The <function>ber_get_next</function> function reads the next BER element.</para>
<sect3 id="gaqso"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
    BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqsg"><title>Parameters</title>
<table frame="topbot" id="gaqsf"><title><function>ber_get_next</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sb</literal></para></entry>
<entry>
<para>Descriptor (socket or file descriptor) from which to read.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>The length of the entire element.</para></entry>
</row>
<row>
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqsk"><title>Description</title>
<para><function>ber_get_next</function> strips off and returns the leading
tag, strips off and returns the length of the entire element, and sets up
a pointer to  <literal>ber</literal> for subsequent calls to decode the element.</para>
</sect3>
</sect2>
<sect2 id="bdaok"><title><function>ber_get_next_buffer</function></title>
<para>The <function>ber_get_next_buffer</function> function reads the next
BER element from a byte buffer.</para>
<note><para>This is an older function included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaol">ber_get_next_buffer_ext
</olink>  instead.</para></note>
<sect3 id="bdaol"><title><function>ber_get_next_buffer_ext</function></title>
<para>The <function>ber_get_next_buffer_ext</function> function reads the
next BER element from a byte buffer.</para>
<note><para><olink targetptr="bdaol">ber_get_next_buffer_ext</olink> is a
new version of the <olink targetptr="bdaok">ber_get_next_buffer</olink> function.
If you are writing a new LDAP client, use <olink targetptr="bdaol">ber_get_next_buffer_ext
</olink> .</para></note>
</sect3>
<sect3 id="gaqtf"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_next_buffer_ext( void *buffer,
    size_t buffer_size, unsigned long *len, BerElement *ber,
    unsigned long *Bytes_Scanned, Sockbuf *sb );</programlisting>
</sect3>
<sect3 id="gaqto"><title>Parameters</title>
<table frame="topbot" id="gaqtd"><title><function>ber_get_next_buffer_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>buffer</literal></para></entry>
<entry>
<para>Pointer to the buffer.</para></entry>
</row>
<row>
<entry>
<para><literal>buffer_size</literal></para></entry>
<entry>
<para>The size of the buffer.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>The length of the entire element.</para></entry>
</row>
<row>
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>Bytes_Scanned</literal></para></entry>
<entry>
<para>Returns the number of bytes actually searched through.</para></entry>
</row>
<row>
<entry>
<para><literal>sb</literal></para></entry>
<entry>
<para>Descriptor (socket or file descriptor) from which to read.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdaom"><title><function>ber_get_null</function></title>
<para>The <function>ber_get_null</function> function is used to read a <literal>NULL
</literal>  element.</para>
<sect3 id="gaqss"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_null( BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqsz"><title>Parameters</title>
<table frame="topbot" id="gaqti"><title><function>ber_get_null</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqsh"><title>Returns</title>
<para>Returns the tag of the element it skips over.</para></sect3>
</sect2>
<sect2 id="bdaon"><title><function>ber_get_option</function></title>
<para>The <function>ber_get_option</function> function is used to retrieve
information about the API and about the specific implementation being used.</para>
<sect3 id="gaqsn"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_get_option( BerElement *ber, int option, void *value );</programlisting>
</sect3>
</sect2>
<sect2 id="bdaoo"><title><function>ber_get_stringa</function></title>
<para>The  <function>ber_get_stringa</function> function is used to  allocate
 memory space into which an octet string is read.</para>
<sect3 id="gaqsj"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_stringa( BerElement *ber, char **buf );</programlisting>
</sect3>
</sect2>
<sect2 id="bdaop"><title><function>ber_get_stringal</function></title>
<para>The  <function>ber_get_stringal</function> function is used to allocate
memory space into which an octet string and its length are read.</para>
<sect3 id="gaqtl"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );</programlisting>
</sect3>
<sect3 id="gaqtk"><title>Description</title>
<para>It takes a <olink targetptr="bdakg">berval</olink> structure, and returns
the result in this parameter.</para></sect3>
</sect2>
<sect2 id="bdaoq"><title><function>ber_get_stringb</function></title>
<para>The  <function>ber_get_stringb</function> function is used to read an
octet string into a preallocated buffer.</para>
<sect3 id="gaqsm"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_get_stringb( BerElement *ber, char *buf,
    unsigned long *len );</programlisting>
</sect3>
<sect3 id="gaqtq"><title>Description</title>
<para>The <literal>len</literal> parameter should be initialized to the size
of the buffer, and will contain the length of the octet string read upon return.
The buffer should be big enough to take the octet string value plus a terminating <literal>
NULL</literal>  byte.</para></sect3>
</sect2>
<sect2 id="bdaor"><title><function>ber_init</function></title>
<para>The <function>ber_init</function> function constructs a new  <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqsv"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
BerElement * ber_init( const struct berval *bv );</programlisting>
</sect3>
<sect3 id="gaqte"><title>Parameters</title>
<table frame="topbot" id="gaqsb"><title><function>ber_init</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>bv</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakg">berval</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqve"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, returns a new <olink targetptr="bdakh">BerElement</olink> containing
a copy of the data in the <literal>bv</literal> argument.</para></listitem>
<listitem><para>If not, returns a <literal>NULL</literal> pointer.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdaos"><title><function>ber_init_w_nullchar</function></title>
<para>The <function>ber_init_w_nullchar</function> function constructs a new <olink targetptr="bdakh">BerElement</olink> with a <literal>NULL</literal> character.</para>
<sect3 id="gaqtu"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_init_w_nullchar( BerElement *ber, int options );</programlisting>
</sect3>
</sect2>
<sect2 id="bdaot"><title><function>ber_next_element</function></title>
<para>The <function>ber_next_element</function> function is used to return
the tag and length of the next element in a set or sequence.</para>
<sect3 id="gaquc"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_next_element( BerElement *ber, unsigned long *len,
    char *last );</programlisting>
</sect3>
<sect3 id="gaqun"><title>Parameters</title>
<table frame="topbot" id="gaquk"><title><function>ber_next_element</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>Pointer to the address of the unsigned long which returns the length
of the next element.</para></entry>
</row>
<row>
<entry>
<para><literal>last</literal></para></entry>
<entry>
<para>Address of the pointer to return the address of the last byte of the
element.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqvc"><title>Returns</title>
<para><literal>NULL</literal> pointer is returned on error.</para></sect3>
<sect3 id="gaquz"><title>Description</title>
<para>The <function>ber_next_element</function> function is used to return
the tag and length of the first element in a set or sequence.</para></sect3>
<sect3 id="gaquq"><title>See Also</title>
<para><olink targetptr="bdaoe">ber_first_element</olink></para></sect3>
</sect2>
<sect2 id="bdaou"><title><function>ber_peek_tag</function></title>
<para>The <function>ber_peek_tag</function> function returns the tag of the
next element to be parsed in the supplied <olink targetptr="bdakh">BerElement</olink> structure.
</para>
<sect3 id="gaqtt"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );</programlisting>
</sect3>
<sect3 id="gaqug"><title>Parameters</title>
<table frame="topbot" id="gaqui"><title><function>ber_peek_tag</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>Pointer to the address of the unsigned long which returns the length
of the next element.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqtr"><title>Returns</title>
<para>Returns the tag of the next element to be read in the  <olink targetptr="bdakh">BerElement</olink> structure. <literal>LBER_DEFAULT</literal> is
returned if there is no further data to be read.</para></sect3>
</sect2>
<sect2 id="bdaov"><title><function>ber_printf</function></title>
<para>The <function>ber_printf</function> function encodes a BER element.</para>
<sect3 id="gaquv"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
ber_printf( BerElement *ber, const char *fmt, ... );</programlisting>
</sect3>
<sect3 id="gaqut"><title>Parameters</title>
<table frame="topbot" id="gaqty"><title><function>ber_printf</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> returned by <olink targetptr="bdany">ber_alloc</olink> or <olink targetptr="bdanz">ber_alloc_t</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>fmt</literal></para></entry>
<entry>
<para>Defines the encoding format string. The format string can contain the
following characters:</para>
<itemizedlist>
<listitem><para><literal>-b</literal> Boolean. An integer parameter should
be supplied. A boolean element is output.</para></listitem>
<listitem><para><literal>-i</literal> Integer. An integer parameter should
be supplied. An integer element is output.</para></listitem>
<listitem><para><literal>-B</literal> Bitstring. A <literal>char *</literal> pointer
to the start of the bitstring is supplied, followed by the number of bits
in the bitstring. A bitstring element is output.</para></listitem>
<listitem><para><literal>-n</literal> Null. No parameter is required. A  <literal>
NULL</literal> element is output.</para></listitem>
<listitem><para><literal>-o</literal> Octet string. A <literal>char *</literal> is
supplied, followed by the length of the string pointed to. An octet string
element is output.</para></listitem>
<listitem><para><literal>-s</literal> Octet string. A <literal>NULL</literal> terminated
string is supplied. An octet string element is output, not including the trailing
 <literal>NULL</literal> octet.</para></listitem>
<listitem><para><literal>-t</literal> Tag. An <literal>int</literal> specifying
the tag to give the next element is provided. This works across calls.</para>
</listitem>
<listitem><para><literal>-v</literal> Several octet strings. A <literal>NULL</literal> terminated
array of char  *s is supplied. Note that a construct like '{v}' is required
to get an actual sequence of octet strings.</para></listitem>
<listitem><para><literal>-{</literal> Begin sequence. No parameter is required.</para>
</listitem>
<listitem><para><literal>-}</literal> End sequence.  No parameter is required.</para>
</listitem>
<listitem><para><literal>-[</literal> Begin set. No parameter is required.</para>
</listitem>
<listitem><para><literal>-]</literal> End set. No parameter is required.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>...</literal></para></entry>
<entry>
<para>Values to be encoded.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqtv"><title>Description</title>
<para>State information is kept with the <literal>ber</literal> parameter
so multiple calls can be made to  <function>ber_printf</function> to append
things to the end of the <olink targetptr="bdakh">BerElement</olink>. <function>ber_printf
</function> interprets and formats its arguments according to the format string <literal>
fmt</literal>. Each character in <literal>fmt</literal> refers to an argument
to <function>ber_printf</function> .</para></sect3>
<sect3 id="gaqup"><title>Returns</title>
<para><literal>-1</literal> if there is an error during encoding.</para></sect3>
</sect2>
<sect2 id="bdaow"><title><function>ber_put_bitstring</function></title>
<para>The <function>ber_put_bitstring</function> function writes a bitstring
value to the given <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaquo"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_bitstring( BerElement *ber, char *str,
    unsigned long bitlen, unsigned long tag );</programlisting>
</sect3>
<sect3 id="gaqus"><title>Description</title>
<para>The <function>ber_put_bitstring</function> function writes <literal>bitlen</literal> bits
starting at <literal>str</literal> as a bitstring value to the given  <olink targetptr="bdakh">BerElement</olink>.</para></sect3>
</sect2>
<sect2 id="bdaox"><title><function>ber_put_boolean</function></title>
<para>The <function>ber_put_boolean</function> function writes a boolean value
to a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqvb"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );</programlisting>
</sect3>
<sect3 id="gaqud"><title>Description</title>
<para>The boolean value is given by <literal>boolval</literal> to the  <olink targetptr="bdakh">BerElement</olink>.</para></sect3>
</sect2>
<sect2 id="bdaoy"><title><function>ber_put_enum</function></title>
<para>The <function>ber_put_enum</function> function writes an enumerated
value to a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaque"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_enum( BerElement *ber, long num, unsigned long tag );</programlisting>
</sect3>
</sect2>
<sect2 id="bdaoz"><title><function>ber_put_int</function></title>
<para>The <function>ber_put_int</function> function writes an integer to a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaquy"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_int( BerElement *ber, long num, unsigned long tag );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapa"><title><function>ber_put_null</function></title>
<para>The <function>ber_put_null</function> function writes a writes a <literal>NULL
</literal>  element to a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaquw"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_null( BerElement *ber, unsigned long tag );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapb"><title><function>ber_put_ostring</function></title>
<para>The <function>ber_put_ostring</function> function writes bytes to a
 <olink targetptr="bdakh">BerElement</olink> as an octet string.</para>
<sect3 id="gaqum"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_ostring( BerElement *ber, char *str,
     unsigned long len, unsigned long tag );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapc"><title><function>ber_put_seq</function></title>
<para>The <function>ber_put_seq</function> function puts a sequence to a  <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqtz"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_seq( BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqts"><title>Parameters</title>
<table frame="topbot" id="gaqua"><title><function>ber_put_seq</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqvd"><title>Description</title>
<para>The <olink targetptr="bdapt">ber_start_seq</olink> function is used
to start a sequence in the <olink targetptr="bdakh">BerElement</olink>. The
end of the sequence is marked by the nearest matching call to <function>ber_put_seq
</function>.</para></sect3>
</sect2>
<sect2 id="bdapd"><title><function>ber_put_set</function></title>
<para>The <function>ber_put_set</function> function puts a set to a  <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqtw"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_set( BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqub"><title>Parameters</title>
<table frame="topbot" id="gaquh"><title><function>ber_put_set</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqtx"><title>Description</title>
<para>The <olink targetptr="bdapu">ber_start_set</olink> function is used
to start a set in the <olink targetptr="bdakh">BerElement</olink>. The end
of the set is marked by the nearest matching call to <function>ber_put_set</function>.
</para></sect3>
</sect2>
<sect2 id="bdape"><title><function>ber_put_string</function></title>
<para>The <function>ber_put_string</function> function writes a <literal>NULL</literal> terminated
string (minus the terminating <literal>0</literal>) to a  <olink targetptr="bdakh">BerElement</olink> as an octet string.</para>
<sect3 id="gaqur"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_put_string( BerElement *ber, char *str, unsigned long tag );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapf"><title><function>ber_read</function></title>
<sect3 id="gaqul"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
long ber_read( BerElement *ber, char *buf, unsigned long len );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapg"><title><function>ber_reset</function></title>
<sect3 id="gaquj"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_reset( BerElement *ber, int was_writing );</programlisting>
</sect3>
</sect2>
<sect2 id="bdaph"><title><function>ber_scanf</function></title>
<para>The <function>ber_scanf</function> function decodes a  <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqux"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );</programlisting>
</sect3>
<sect3 id="gaquu"><title>Parameters</title>
<table frame="topbot" id="gaqva" remap="*Standard"><title><function>ber_scanf</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> as returned
by <olink targetptr="bdaoj">ber_get_next</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>fmt</literal></para></entry>
<entry>
<para>Defines the encoding format string. The format string can contain the
following characters:</para>
<itemizedlist>
<listitem><para><literal>-a</literal> Octet string. A <literal>char **</literal> should
be supplied. Memory is allocated, filled  with the contents of the octet string,
 <literal>NULL</literal> terminated, and returned in the  parameter.</para>
</listitem>
<listitem><para><literal>-s</literal> Octet string. A <literal>char *</literal> 
buffer should be supplied, followed by a pointer to an integer initialized
to the size of the buffer. Upon return, the  <literal>NULL</literal> terminated
octet string is put into the buffer, and the integer is set to the actual
size of the octet string.</para></listitem>
<listitem><para><literal>-O</literal> Octet string. A <literal>struct ber_val
**</literal> should be supplied, which upon return points to a memory allocated <literal>
struct berval</literal>  containing the octet  string and its length. Call
 <olink targetptr="bdaoc">ber_bvfree</olink> to free allocated memory.</para>
</listitem>
<listitem><para><literal>-b</literal> Boolean. A pointer to an integer should
be supplied.</para></listitem>
<listitem><para><literal>-i</literal> Integer. A pointer to an integer should
be supplied.</para></listitem>
<listitem><para><literal>-B</literal> Bitstring. A <literal>char **</literal> should
be supplied which will point to the memory allocated bits, followed by an
 <literal>unsigned long *</literal>, which will point to the  length (in bits)
of the bitstring returned.</para></listitem>
<listitem><para><literal>-n</literal> Null. No parameter is required. The
element is simply skipped if it is recognized.</para></listitem>
<listitem><para><literal>-v</literal> Sequence of octet strings. A <literal>char
***</literal> should be  supplied, which upon return points to a memory allocated
 <literal>NULL</literal> terminated array of <literal>char *</literal>s containing
the octet strings. <literal>NULL</literal> is returned if the sequence is
empty.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>fmt</literal> (continued)</para></entry>
<entry>
<itemizedlist>
<listitem><para><literal>-V</literal> Sequence of octet strings with lengths.
A  <literal>struct  berval  ***</literal>  should be supplied, which upon
return points to a memory allocated, <literal>NULL</literal> terminated array
of <literal>struct berval  *</literal>s containing the octet strings and their
lengths. <literal>NULL</literal> is returned if the sequence is empty. <olink targetptr="bdaoa">ber_bvecfree</olink> can be called to free the allocated
memory.</para></listitem>
<listitem><para><literal>-x</literal> Skip element. The next element is skipped.</para>
</listitem>
<listitem><para><literal>-{</literal> Begin sequence. No parameter is required.
The initial sequence tag and length are skipped.</para></listitem>
<listitem><para><literal>-}</literal> End sequence. No parameter is required
and no action is taken.</para></listitem>
<listitem><para><literal>-[</literal> Begin set. No parameter is required.
The initial set tag and length are skipped.</para></listitem>
<listitem><para><literal>-]</literal> End set. No parameter is required and
no action is taken.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>...</literal></para></entry>
<entry>
<para>Values to be encoded.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaquf"><title>Description</title>
<para><function>ber_scanf</function> reads from <literal>ber</literal>, interprets
the bytes according to the format string <literal>fmt</literal>, and stores
the results in its additional arguments. The format string contains conversion
specifications which are used to direct the interpretation of the BER element.</para>
</sect3>
<sect3 id="gaqvt"><title>See Also</title>
<para><olink targetptr="bdaov">ber_printf</olink></para></sect3>
</sect2>
<sect2 id="bdapi"><title><function>ber_set_option</function></title>
<sect3 id="gaqvq"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_set_option( BerElement *ber, int option, void *value );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapj"><title><function>ber_set_string_translators</function></title>
<sect3 id="gaqvl"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapk"><title><function>ber_skip_tag</function></title>
<para>The <function>ber_skip_tag</function> function advances the pointer
to a <olink targetptr="bdakh">BerElement</olink> past the first tag and length
to the next tag.</para>
<sect3 id="gaqvx"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</programlisting>
</sect3>
<sect3 id="gaqwn"><title>Parameters</title>
<table frame="topbot" id="gaqws"><title><function>ber_skip_tag</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>len</literal></para></entry>
<entry>
<para>Pointer to the length of the value to be skipped.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqvy"><title>Description</title>
<para><function>ber_skip_tag</function> should only be used with constructed
types and situations when a BER encoding is used as the value of an octet
string.</para></sect3>
<sect3 id="gaqwi"><title>See Also</title>
<para><olink targetptr="bdaou">ber_peek_tag</olink></para></sect3>
</sect2>
<sect2 id="bdapl"><title><function>ber_sockbuf_alloc</function></title>
<sect3 id="gaqwg"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
Sockbuf* ber_sockbuf_alloc( void );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapm"><title><function>ber_sockbuf_free</function></title>
<sect3 id="gaqvh"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_sockbuf_free( Sockbuf* p );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapn"><title><function>ber_sockbuf_free_data</function></title>
<sect3 id="gaqwa"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_sockbuf_free_data(Sockbuf *p);</programlisting>
</sect3>
</sect2>
<sect2 id="bdapo"><title><function>ber_sockbuf_get_option</function></title>
<sect3 id="gaqwp"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapp"><title><function>ber_sockbuf_set_option</function></title>
<sect3 id="gaqwo"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapq"><title><function>ber_special_alloc</function></title>
<para>The <function>ber_special_alloc</function> function allocates a  <olink targetptr="bdakh">BerElement</olink> structure plus some extra memory.</para>
<sect3 id="gaqvi"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void* ber_special_alloc( size_t size, BerElement **ppBer );</programlisting>
</sect3>
<sect3 id="gaqwf"><title>Returns</title>
<para>Returns a pointer to the <olink targetptr="bdakh">BerElement</olink> and
a pointer to the extra memory.</para></sect3>
<sect3 id="gaqvu"><title>Description</title>
<para><function>ber_special_alloc</function> allocates a ber data buffer within
the same block, thus saving a call to calloc later when we read data.</para>
</sect3>
</sect2>
<sect2 id="bdapr"><title><function>ber_special_free</function></title>
<para>The <function>ber_special_free</function> function frees an allocated <olink targetptr="bdakh">BerElement</olink> structure.</para>
<sect3 id="gaqwv"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_special_free( void* buf, BerElement *ber );</programlisting>
</sect3>
<sect3 id="gaqwm"><title>See Also</title>
<para><olink targetptr="bdapq">ber_special_alloc</olink></para></sect3>
</sect2>
<sect2 id="bdaps"><title><function>ber_stack_init</function></title>
<sect3 id="gaqvv"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int) LDAP_CALL ber_stack_init(BerElement *ber, int options,
    char * buf, size_t size);</programlisting>
</sect3>
</sect2>
<sect2 id="bdapt"><title><function>ber_start_seq</function></title>
<para>The <function>ber_start_seq</function> function is used to start a sequence
in a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqwl"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_start_seq( BerElement *ber, unsigned long tag );</programlisting>
</sect3>
<sect3 id="gaqvw"><title>See Also</title>
<para><olink targetptr="bdapc">ber_put_seq</olink></para></sect3>
</sect2>
<sect2 id="bdapu"><title><function>ber_start_set</function></title>
<para>The <function>ber_start_seq</function> function is used to start a set
in a <olink targetptr="bdakh">BerElement</olink>.</para>
<sect3 id="gaqvj"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
int ber_start_set( BerElement *ber, unsigned long tag );</programlisting>
</sect3>
<sect3 id="gaqww"><title>See Also</title>
<para><olink targetptr="bdapd">ber_put_set</olink></para></sect3>
</sect2>
<sect2 id="bdapv"><title><function>ber_svecfree</function></title>
<sect3 id="gaqwc"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
void ber_svecfree( char **vals );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapw"><title><function>ber_write</function></title>
<sect3 id="gaqvg"><title>Syntax</title>
<programlisting>#include &lt;lber.h>
long ber_write( BerElement *ber, char *buf,
    unsigned long len, int nosos );</programlisting>
</sect3>
</sect2>
<sect2 id="bdapx"><title><function>ldap_abandon</function></title>
<para>The <function>ldap_abandon</function> function cancels an asynchronous
LDAP operation that is in progress.</para>
<note><para>This is an older function included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdapy">ldap_abandon_ext
</olink>  instead.</para></note>
<sect3 id="gaqvm"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_abandon( LDAP *ld, int msgid );</programlisting>
</sect3>
<sect3 id="gaqwh"><title>Parameters</title>
<table frame="topbot" id="gaqvn"><title><function>ldap_abandon</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>msgid</literal></para></entry>
<entry>
<para>Message ID of an LDAP operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqwe"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
<note><para>The appropriate LDAP error code is also set in the  <olink targetptr="bdakj">LDAP</olink> structure. You can retrieve the error code
by calling  <olink targetptr="bdasq">ldap_get_lderrno</olink>. Some possible
codes are:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</note>
</sect3>
<sect3 id="gaqvo"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdapy">ldap_abandon_ext
</olink>.</para></sect3>
<sect3 id="gaqwr"><title>Example</title>
<para><olink targetptr="cancel-url-search">Example 21&ndash;2</olink>  cancels
an <olink targetptr="bdawm">ldap_url_search</olink> operation, abandoning
the results of the operation.</para>
<example id="cancel-url-search"><title>Cancelling an <function>ldap_url_search</function> Operation
</title>
<programlisting>LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
int msgid;
...
/* Initiate a search operation */
msgid = ldap_url_search( ld, url, 0 );
...
/* Abandon the search operation */
if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_abandon" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqwu"><title>See Also</title>
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></sect3>
</sect2>
<sect2 id="bdapy"><title><function>ldap_abandon_ext</function></title>
<para>The <function>ldap_abandon_ext</function> function cancels an asynchronous
LDAP operation that is in progress.</para>
<note><para><olink targetptr="bdapy">ldap_abandon_ext</olink> is a new version
of the <olink targetptr="bdapx">ldap_abandon</olink> function. If you are
writing a new LDAP client, use <olink targetptr="bdapy">ldap_abandon_ext</olink>.
</para></note>
<sect3 id="gaqwt"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_abandon_ext( LDAP *ld, int msgid,
     LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="gaqvp"><title>Parameters</title>
<table frame="topbot" id="gaqwb"><title><function>ldap_abandon_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>msgid</literal></para></entry>
<entry>
<para>Message ID of an LDAP operation to identify the operation to be cancelled.
When you call an asynchronous function such as <olink targetptr="bdauz">ldap_search_ext
</olink>, the <literal>msgidp</literal> argument returns a pointer to a message
ID that uniquely identifies the operation. Thus, when you call  <olink targetptr="bdapy">ldap_abandon_ext</olink>, your LDAP client is able to send
a request specifying the message ID of the operation to be cancelled.</para>
</entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqwq"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqwd"><title>Description</title>
<para>The <function>ldap_abandon_ext</function> function cancels an asynchronous
LDAP operation that is in progress. For example, if you called  <olink targetptr="bdauz">ldap_search_ext</olink> to initiate an LDAP search operation
on the server, you can call <function>ldap_abandon_ext</function> to cancel
it. When you call  <function>ldap_abandon_ext</function>, the function checks
to see if the results of the operation have already been returned. If so, <function>
ldap_abandon_ext</function> deletes the message ID from the queue of pending
messages. If the results have not been returned,  <function>ldap_abandon_ext</function> sends
a request to abandon the operation. Once cancelled, the results of the operation
will not be returned, even if you subsequently call <olink targetptr="bdauu">ldap_result
</olink> to retrieve them. To identify the operation to be cancelled, specify
the message ID of the operation in the <literal>msgid</literal> argument of
the <function>ldap_abandon_ext</function> function.</para></sect3>
<sect3 id="gaqwk"><title>Example</title>
<para><olink targetptr="abandon-example">Example 21&ndash;3</olink> cancels
an <olink targetptr="bdawm">ldap_url_search</olink> operation, abandoning
the results of the operation.</para>
<example id="abandon-example"><title>Using <function>ldap_abandon_ext</function></title>
<programlisting>LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
int msgid;
LDAPControl **srvrctrls, **clntctrls;
...
/* Initiate a search operation */
msgid = ldap_url_search( ld, url, 0 );
...
/* Abandon the search operation */
if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls )
    != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_abandon" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqvf"><title>See Also</title>
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqp">ldap_compare_ext
</olink> , <olink targetptr="bdari">ldap_delete_ext</olink>,  <olink targetptr="bdaru">ldap_extended_operation</olink>, <olink targetptr="bdatn">ldap_modify_ext
</olink>, <olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdauw">
ldap_sasl_bind</olink> , <olink targetptr="bdauz">ldap_search_ext</olink>,
 <olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdawm">ldap_url_search
</olink></para></sect3>
</sect2>
<sect2 id="bdapz"><title><function>ldap_add</function></title>
<para>The <function>ldap_add</function> function adds a new entry to the directory
asynchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaqa">ldap_add_ext</olink> 
instead.</para></note>
<sect3 id="gaqwj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );</programlisting>
</sect3>
<sect3 id="gaqvs"><title>Parameters</title>
<table frame="topbot" id="gaqvk"><title><function>ldap_add</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to add. With the exception of the leftmost component,
all components of the DN (for example, <literal>o=organization</literal> or <literal>
c=country</literal>) must already exist.</para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
the new entry.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqvr"><title>Returns</title>
<para>The message ID of the <function>ldap_add</function> operation.</para>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
See <olink targetptr="bdaqb">ldap_add_ext_s</olink> for a list of possible
result codes for the LDAP add operation.</para></note>
</sect3>
<sect3 id="gaqvz"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaqa">ldap_add_ext
</olink> .</para></sect3>
<sect3 id="gaqxo"><title>Example</title>
<para><olink targetptr="adding-entry-example">Example 21&ndash;4</olink> adds
a new entry to the directory.</para>
<example id="adding-entry-example"><title>Using <function>ldap_add</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the new entry. Note that "dc=example,dc=com" and
   "ou=People,dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";

/* To add a "person" entry, you must specify values for the sn, cn,
   and objectClass attributes. (These are required attributes.) */
char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values
   to the array. */
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a
   subclass of "top", "person", and "organizationalPerson". You should add
   all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson",
                               "inetOrgPerson", NULL };
...
/* Specify the value and type of each attribute in separate LDAPMod
   structures */
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &amp;attribute1;
list_of_attrs[1] = &amp;attribute2;
list_of_attrs[2] = &amp;attribute3;
list_of_attrs[3] = NULL;
...
/* Set up the timeout period for adding the new entry */
tv.tv_sec = tv.tv_usec = 0;

/* Add the user "Barbara Jensen" */
if ( ( msgid = ldap_add( ld, dn, list_of_attrs ) ) == -1 ) {
  ldap_perror( ld, "ldap_add" );
  return( 1 );
}

/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &amp;tv, &amp;result ) ) == 0 ) {
  ...
  /* do other work while waiting for the operation to complete */
  ...
}

/* Check the result to see if any errors occurred */
if (( rc = ldap_result2error( ld, result, 1 )) != LDAP_SUCCESS ) {
  printf( "Error while adding entry: %s\n", ldap_err2string( rc ));
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqyi"><title>See Also</title>
<para><olink targetptr="bdaqa">ldap_add_ext</olink></para></sect3>
</sect2>
<sect2 id="bdaqa"><title><function>ldap_add_ext</function></title>
<para>The <function>ldap_add_ext</function> function adds a new entry to the
directory asynchronously.</para>
<note><para><olink targetptr="bdaqa">ldap_add_ext</olink> is a new version
of the <olink targetptr="bdapz">ldap_add</olink> function. If you are writing
a new LDAP client, use <olink targetptr="bdaqa">ldap_add_ext</olink>.</para>
</note>
<sect3 id="gaqxp"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     int *msgidp );</programlisting>
</sect3>
<sect3 id="gaqxc"><title>Parameters</title>
<table frame="topbot" id="gaqyd"><title><function>ldap_add_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to add. With the exception of the leftmost component,
all components of the DN (for example, <literal>o=organization</literal> or <literal>
c=country</literal>) must already exist.</para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
the new entry.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqxs"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqxw"><title>Description</title>
<para>The <function>ldap_add_ext</function> adds a new entry to the directory.
To add a new entry to the directory, you need to specify:</para>
<itemizedlist>
<listitem><para>A unique DN identifying the new entry.</para><para>Use the
 <literal>dn</literal> argument to specify the DN of the new entry. The parents
of the entry should already exist. For example, if you are adding the entry <literal>
uid=bjensen,ou=People,dc=example,dc=com</literal> , the entries <literal>ou=People
</literal> and <literal>dc=example,dc=com</literal>  must already exist in
the directory.</para></listitem>
<listitem><para>A set of attributes for the new entry.</para><para>Create
an <olink targetptr="bdalz">LDAPMod</olink> structure for each attribute.
Set the  <literal>mod_op</literal> field to <literal>0</literal> if the attribute
values are string values. To specify values that consist of binary data (such
as a sound file or a JPEG file), set the <literal>mod_op</literal> field to <literal>
LDAP_MOD_BVALUES</literal>. Create an array of these <olink targetptr="bdalz">LDAPMod
</olink> structures and pass the array as the <literal>attrs</literal> argument.</para>
<para><function>ldap_add_ext</function>  is an asynchronous function; it does
not directly return results. In order to get the results of the asynchronous
operation, you need to call the  <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdaun">ldap_parse_result</olink> functions. If you want the results
to be returned directly by the function, call the synchronous function <olink targetptr="bdaqb">ldap_add_ext_s</olink>. For a list of possible result codes
for an LDAP add operation, see the <olink targetptr="bdaqb">ldap_add_ext_s</olink> 
function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqxd"><title>See Also</title>
<para><olink targetptr="bdaqb">ldap_add_ext_s</olink>,  <olink targetptr="bdauu">
ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result</olink>, <olink targetptr="bdalz">LDAPMod</olink></para></sect3>
</sect2>
<sect2 id="bdaqb"><title><function>ldap_add_ext_s</function></title>
<para>The <function>ldap_add_ext_s</function> function adds a new entry to
the directory synchronously.</para>
<note><para><olink targetptr="bdaqb">ldap_add_ext_s</olink> is a new version
of the <olink targetptr="bdaqc">ldap_add_s</olink> function. If you are writing
a new LDAP client, use <olink targetptr="bdaqb">ldap_add_ext_s</olink>.</para>
</note>
<sect3 id="gaqyl"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
     LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="gaqxe"><title>Parameters</title>
<table frame="topbot" id="gaqyk"><title><function>ldap_add_ext_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to add. With the exception of the leftmost component,
all components of the DN (for example, <literal>o=organization</literal> or <literal>
c=country</literal>) must already exist.</para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
the new entry.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqyn"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="gaqxx"><title>Description</title>
<para>The <function>ldap_add_ext_s</function> function adds a new entry to
the directory. To add a new entry to the directory, you need to specify:</para>
<itemizedlist>
<listitem><para>A unique DN identifying the new entry.</para><para>Use the
 <literal>dn</literal> argument to specify the DN of the new entry. The parents
of the entry should already exist. For example, if you are adding the entry <literal>
uid=bjensen,ou=People,dc=example,dc=com</literal> , the entries <literal>ou=People
</literal> and <literal>dc=example,dc=com</literal>  must already exist in
the directory.</para></listitem>
<listitem><para>A set of attributes for the new entry.</para><para>Create
an <olink targetptr="bdalz">LDAPMod</olink> structure for each attribute.
Set the  <literal>mod_op</literal> field to <literal>0</literal> if the attribute
values are string values. To specify values that consist of binary data (such
as a sound file or a JPEG file), set the <literal>mod_op</literal> field to <literal>
LDAP_MOD_BVALUES</literal>. Create an array of these <olink targetptr="bdalz">LDAPMod
</olink> structures and pass the array as the <literal>attrs</literal> argument.</para>
<para><function>ldap_add_ext_s</function>  is a synchronous function; it directly
returns the results of the operation. If you want to perform other operations
while waiting for the results of this operation, call the asynchronous function <olink targetptr="bdaqa">ldap_add_ext</olink>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaqxz"><title>See Also</title>
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdalz">LDAPMod
</olink></para></sect3>
</sect2>
<sect2 id="bdaqc"><title><function>ldap_add_s</function></title>
<para>The <function>ldap_add_s</function> function adds a new entry to the
directory synchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaqb">ldap_add_ext_s
</olink>  instead.</para></note>
<sect3 id="gaqyq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );</programlisting>
</sect3>
<sect3 id="gaqyr"><title>Parameters</title>
<table frame="topbot" id="gaqym"><title><function>ldap_add_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to add. With the exception of the leftmost component,
all components of the DN (for example, <literal>o=organization</literal> or <literal>
c=country</literal>) must already exist.</para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
the new entry.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqxi"><title>Returns</title>
<para>See <olink targetptr="bdaqb">ldap_add_ext_s</olink> for a list of possible
return codes.</para></sect3>
<sect3 id="gaqxg"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaqb">ldap_add_ext_s
</olink> .</para></sect3>
<sect3 id="gaqxa"><title>Example</title>
<para><olink targetptr="ldap-add-s-example">Example 21&ndash;5</olink> adds
a new entry to the directory.</para>
<example id="ldap-add-s-example"><title>Using <function>ldap_add_s</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;

/* Distinguished name of the new entry. Note that "dc=example,dc=com" and
   "ou=People,dc=example,dc=com" must already exist in the directory. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";

/* To add a "person" entry, you must specify values for the sn, cn,
   and objectClass attributes. (These are required attributes.) */
char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values
   to the array. */
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a
 * subclass of "top", "person", and "organizationalPerson". You should add 
 * all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson",
                               "inetOrgPerson", NULL };
...
/* Specify the value and type of each attribute in separate LDAPMod 
   structures */
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &amp;attribute1;
list_of_attrs[1] = &amp;attribute2;
list_of_attrs[2] = &amp;attribute3;
list_of_attrs[3] = NULL;
...
/* Add the user "Barbara Jensen" */
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_add_s" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqxt"><title>See Also</title>
<para><olink targetptr="bdaqb">ldap_add_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdaqd"><title><function>ldap_ber_free</function></title>
<para>The <function>ldap_ber_free</function> function frees a  <olink targetptr="bdakh">BerElement</olink> structure from memory.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaog">ber_free</olink> instead.
Except in name, the two functions are identical.</para></note>
<sect3 id="gaqwy"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_ber_free( BerElement *ber, int freebuf );</programlisting>
</sect3>
<sect3 id="gaqwx"><title>Parameters</title>
<table frame="topbot" id="gaqxy"><title><function>ldap_ber_free</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
that you want to free.</para></entry>
</row>
<row>
<entry>
<para><literal>freebuf</literal></para></entry>
<entry>
<para>Specifies whether or not to free the buffer in the  <olink targetptr="bdakh">BerElement</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqxj"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaog">ber_free
</olink> .</para></sect3>
<sect3 id="gaqxn"><title>See Also</title>
<para><olink targetptr="bdaog">ber_free</olink></para></sect3>
</sect2>
<sect2 id="bdaqe"><title><function>ldap_bind</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavi">ldap_simple_bind</olink> instead.</para></note>
<para><function>ldap_bind</function> can be used when the authentication method
being used needs to be selected at runtime.</para>
<sect3 id="gaqxm"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
 ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );</programlisting>
</sect3>
<sect3 id="gaqyo"><title>Parameters</title>
<table frame="topbot" id="gaqxk"><title><function>ldap_bind</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>who</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
</para></entry>
</row>
<row>
<entry>
<para><literal>passwd</literal></para></entry>
<entry>
<para>Password of the user who wants to authenticate. For anonymous authentication,
set this or the who argument to <literal>NULL</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>method</literal></para></entry>
<entry>
<para>Defines the authentication method to be used. It should be set to  <literal>
LDAP_AUTH_SIMPLE</literal> to select simple authentication.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqye"><title>Returns</title>
<para><function>ldap_bind</function> returns the message ID of the request
it initiates.</para></sect3>
<sect3 id="gaqxu"><title>Description</title>
<para>This is an asynchronous function that authenticates a specified entry
to the directory. After a connection is made to an LDAP server using <olink targetptr="bdauj">ldap_open</olink>, a bind operation must be performed before
other operations can be attempted over the connection.</para></sect3>
<sect3 id="gaqyg"><title>See Also</title>
<para><olink targetptr="bdauj">ldap_open</olink>, <olink targetptr="bdasv">ldap_init
</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdaqf">ldap_bind_s</olink></para></sect3>
</sect2>
<sect2 id="bdaqf"><title><function>ldap_bind_s</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavj">ldap_simple_bind_s</olink> instead.</para></note>
<para><function>ldap_bind_s</function> can be used when the authentication
method needs to be selected at runtime.</para>
<sect3 id="gaqxl"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
 ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );</programlisting>
</sect3>
<sect3 id="gaqyc"><title>Parameters</title>
<table frame="topbot" id="gaqyj"><title><function>ldap_bind_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>who</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
</para></entry>
</row>
<row>
<entry>
<para><literal>cred</literal></para></entry>
<entry>
<para>Password of the user who wants to authenticate. For anonymous authentication,
set this or the who argument to <literal>NULL</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>method</literal></para></entry>
<entry>
<para>Defines the authentication method to be used. It should be set to  <literal>
LDAP_AUTH_SIMPLE</literal> to select simple authentication.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqya"><title>Returns</title>
<para><function>ldap_bind_s</function> returns an LDAP error indication.</para>
</sect3>
<sect3 id="gaqxr"><title>Description</title>
<para>This is a synchronous function that authenticates a specified entry
to the directory. After a connection is made to an LDAP server using <olink targetptr="bdauj">ldap_open</olink> , a bind operation must be  performed
before other operations can be attempted over the connection.</para></sect3>
<sect3 id="gaqyh"><title>See Also</title>
<para><olink targetptr="bdauj">ldap_open</olink>, <olink targetptr="bdasv">ldap_init
</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdaqe">ldap_bind</olink></para></sect3>
</sect2>
<sect2 id="bdaqg"><title><function>ldap_build_filter</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaqz">ldap_create_filter</olink> instead.</para></note>
<sect3 id="gaqxq"><title>See Also</title>
<para><olink targetptr="bdaqz">ldap_create_filter</olink></para></sect3>
</sect2>
<sect2 id="bdaqh"><title><function>ldap_cache_flush</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use the
 <literal>ldap_memcache_*</literal> functions instead.</para></note>
<para>For more specific information, see the header file <literal>ldap-deprecated.h
</literal> .</para>
<sect3 id="gaqxv"><title>See Also</title>
<para><olink targetptr="bdati">ldap_memcache_init</olink>,  <olink targetptr="bdatj">ldap_memcache_set</olink>, <olink targetptr="bdath">ldap_memcache_get
</olink>, <olink targetptr="bdatk">ldap_memcache_update</olink>, <olink targetptr="bdatg">ldap_memcache_flush</olink> , <olink targetptr="bdatf">ldap_memcache_destroy
</olink></para></sect3>
</sect2>
<sect2 id="bdaqi"><title><function>ldap_charray_add</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para>
<sect3 id="bdaqj"><title><function>ldap_charray_dup</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para></sect3>
</sect2>
<sect2 id="bdaqk"><title><function>ldap_charray_free</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para>
<sect3 id="bdaql"><title><function>ldap_charray_inlist</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para></sect3>
</sect2>
<sect2 id="bdaqm"><title><function>ldap_charray_merge</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para>
<sect3 id="bdaqn"><title><function>ldap_charray_position</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
</literal> .</para></sect3>
</sect2>
<sect2 id="bdaqo"><title><function>ldap_compare</function></title>
<para>The <function>ldap_compare</function> function asynchronously determines
if an attribute of an entry contains a specified value.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaqp">ldap_compare_ext
</olink>  instead.</para></note>
<sect3 id="gaqxf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_compare( LDAP *ld, const char *dn, const char *attr,
     const char *value );</programlisting>
</sect3>
<sect3 id="gaqyf"><title>Parameters</title>
<table frame="topbot" id="gaqwz"><title><function>ldap_compare</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry used in the comparison.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Attribute type that you want to check the value against.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Value that you want to compare against the attribute values.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqxh"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_compare</function> operation.</para>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
See <olink targetptr="bdaqq">ldap_compare_ext_s</olink> function for a list
of possible result codes for the LDAP compare operation.</para></note>
</sect3>
<sect3 id="gaqyb"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaqp">ldap_compare_ext
</olink> .</para></sect3>
<sect3 id="gaqyp"><title>Example</title>
<para><olink targetptr="ldap-compare-example">Example 21&ndash;6</olink> checks
to see if Barbara Jensen has the email address <literal>bjensen@example.com</literal>.
</para>
<example id="ldap-compare-example"><title>Using <function>ldap_compare</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
int msgid;
...
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" );
...</programlisting>
</example>
</sect3>
<sect3 id="gaqxb"><title>See Also</title>
<para><olink targetptr="bdaqp">ldap_compare_ext</olink></para></sect3>
</sect2>
<sect2 id="bdaqp"><title><function>ldap_compare_ext</function></title>
<para>The <function>ldap_compare_ext</function> function asynchronously determines
if an attribute of an entry contains a specified value.</para>
<note><para><olink targetptr="bdaqp">ldap_compare_ext</olink> is a new version
of the <olink targetptr="bdaqo">ldap_compare</olink> function. If you are
writing a new LDAP client, use <olink targetptr="bdaqp">ldap_compare_ext</olink>.
</para></note>
<sect3 id="gaqzh"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_compare_ext( LDAP *ld, const char *dn, const char *attr,
     struct berval *bvalue, LDAPControl **serverctrls,
     LDAPControl **clientctrls, int *msgidp );</programlisting>
</sect3>
<sect3 id="gaqzs"><title>Parameters</title>
<table frame="topbot" id="gaqzv"><title><function>ldap_compare_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry used in the comparison.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Attribute type that you want to check the value against.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Value that you want to compare against the attribute values.</para>
</entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqzj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
</note>
</sect3>
<sect3 id="gaqzf"><title>Returns</title>
<para>For a list of the possible result codes for an LDAP compare operation,
see <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para></sect3>
<sect3 id="gaqyx"><title>Description</title>
<para>The <function>ldap_compare_ext</function> function compares the value
of an attribute in an entry against a specified value. Because <function>ldap_compare_ext
</function>  is an asynchronous function, it does not directly return results.
If you want the results to be returned directly by the function, call the
synchronous function <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para>
</sect3>
<sect3 id="gaqzc"><title>See Also</title>
<para><olink targetptr="bdaqq">ldap_compare_ext_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
</olink></para></sect3>
</sect2>
<sect2 id="bdaqq"><title><function>ldap_compare_ext_s</function></title>
<para>The <function>ldap_compare_ext_s</function> function synchronously determines
if an attribute of an entry contains a specified value.</para>
<sect3 id="gaqyt"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_compare_ext_s( LDAP *ld, const char *dn,
     const char *attr, struct berval *bvalue,
    LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="gaqzu"><title>Parameters</title>
<table frame="topbot" id="gaqze"><title><function>ldap_compare_ext_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry used in the comparison.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Attribute type that you want to check the value against.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Value that you want to compare against the attribute values.</para>
</entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqyw"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_COMPARE_TRUE</errorcode> if the entry contains
the attribute value.</para></listitem>
<listitem><para><errorcode>LDAP_COMPARE_FALSE</errorcode> if the entry does
not contain the attribute value.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="gaqyy"><title>Description</title>
<para>The <function>ldap_compare_ext_s</function> function compares the value
of an attribute in an entry against a specified value. <function>ldap_compare_ext_s
</function> is a synchronous function, which directly returns the results
of the operation. If you want to perform other operations while waiting for
the results of this operation, call the asynchronous function <olink targetptr="bdaqp">ldap_compare_ext</olink>.</para></sect3>
<sect3 id="gaqzt"><title>See Also</title>
<para><olink targetptr="bdaqp">ldap_compare_ext</olink></para></sect3>
</sect2>
<sect2 id="bdaqr"><title><function>ldap_compare_s</function></title>
<para>The <function>ldap_compare_s</function> function synchronously determines
if an attribute of an entry contains a specified value.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdaqq">ldap_compare_ext_s
</olink>  instead.</para></note>
<sect3 id="gaqzl"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_compare_s( LDAP *ld, const char *dn,
     const char *attr, const char *value );</programlisting>
</sect3>
<sect3 id="gaqzk"><title>Parameters</title>
<table frame="topbot" id="gaqzp"><title><function>ldap_compare_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry used in the comparison.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Attribute type that you want to check the value against.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Value that you want to compare against the attribute values.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqzg"><title>Returns</title>
<para>For a list of the possible result codes for an LDAP compare operation,
see <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para></sect3>
<sect3 id="gaqzz"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaqq">ldap_compare_ext_s
</olink> .</para></sect3>
<sect3 id="gaqzy"><title>Example</title>
<para><olink targetptr="ldap-compare-s-example">Example 21&ndash;7</olink> checks
to see if Barbara Jensen has the email address <literal>bjensen@example.com</literal>.
</para>
<example id="ldap-compare-s-example"><title>Using <function>ldap_compare_s</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
int has_value;
...
has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" );
switch ( has_value ) {
  case LDAP_COMPARE_TRUE:
    printf( "The mail attribute contains bjensen@example.com.\n");
    break;
  case LDAP_COMPARE_FALSE:
    printf( "The mail attribute does not contain bjensen@example.com.\n");
    break;
  default:
    ldap_perror( ld, "ldap_compare_s" );
    return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaqzo"><title>See Also</title>
<para><olink targetptr="bdaqq">ldap_compare_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdaqs"><title><function>ldap_control_free</function></title>
<para>The <function>ldap_control_free</function> function frees an  <olink targetptr="bdala">LDAPControl</olink> structure from memory.</para>
<sect3 id="gaqzx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
void ldap_control_free( LDAPControl *ctrl );</programlisting>
</sect3>
<sect3 id="gaqyv"><title>Parameters</title>
<table frame="topbot" id="gaqzn"><title><function>ldap_control_free</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ctrl</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
that you want to free from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqzi"><title>Description</title>
<para>The <function>ldap_control_free</function> function frees an  <olink targetptr="bdala">LDAPControl</olink> structure from memory. You should call
this function to free controls that you create; for example, if you call the <olink targetptr="bdare">ldap_create_sort_control</olink>  function.</para></sect3>
<sect3 id="gaqzr"><title>See Also</title>
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></sect3>
</sect2>
<sect2 id="bdaqt"><title><function>ldap_controls_free</function></title>
<para>The <function>ldap_controls_free</function> function frees an array
of <olink targetptr="bdala">LDAPControl</olink> structures from memory.</para>
<sect3 id="gaqzq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
void ldap_controls_free( LDAPControl **ctrls );</programlisting>
</sect3>
<sect3 id="gaqzd"><title>Parameters</title>
<table frame="topbot" id="gaqzm"><title><function>ldap_controls_free</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
that you want to free from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqyu"><title>Description</title>
<para>The <function>ldap_controls_free</function> function frees an array
of <olink targetptr="bdala">LDAPControl</olink> structures from memory. You
should call this function to free arrays of controls that you create or any
arrays returned by <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
</sect3>
<sect3 id="gaqyz"><title>See Also</title>
<para><olink targetptr="bdaqs">ldap_control_free</olink>,  <olink targetptr="bdaun">ldap_parse_result</olink></para></sect3>
</sect2>
<sect2 id="bdaqu"><title><function>ldap_count_entries</function></title>
<para>The <function>ldap_count_entries</function> function returns the number
of <olink targetptr="bdaly">LDAPMessage</olink> structures representing directory
entries in a chain of search results.</para>
<sect3 id="gaqys"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_count_entries( LDAP *ld, LDAPMessage *result );</programlisting>
</sect3>
<sect3 id="gaqza"><title>Parameters</title>
<table frame="topbot" id="gaqzb"><title><function>ldap_count_entries</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Chain of search results, represented by pointer to an  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaqzw"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, the number of <olink targetptr="bdaly">LDAPMessage
</olink>  structures of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> in
a chain of search results. If there are no structures of this type, returns <literal>
0</literal>.</para></listitem>
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
connection handle.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garag"><title>Description</title>
<para>The <function>ldap_count_entries</function> function returns the number
of <olink targetptr="bdaly">LDAPMessage</olink> structures representing directory
entries in a chain of search results. These messages have the type <literal>LDAP_RES_SEARCH_ENTRY
</literal> .</para>
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in the middle of the chain of results, the function counts only the entries
between that structure and the last structure in the chain. In this type of
situation, the function does not return the count of all entries in the chain.</para>
</note>
</sect3>
<sect3 id="garaf"><title>Example</title>
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
<sect3 id="garbe"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry
</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdaud">ldap_next_message</olink></para></sect3>
</sect2>
<sect2 id="bdaqv"><title><function>ldap_count_messages</function></title>
<para>The <function>ldap_count_messages</function> function returns the number
of <olink targetptr="bdaly">LDAPMessage</olink> structures in a chain of search
results.</para>
<sect3 id="garbo"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_count_messages( LDAP *ld, LDAPMessage *res );</programlisting>
</sect3>
<sect3 id="garbl"><title>Parameters</title>
<table frame="topbot" id="garbn"><title><function>ldap_count_messages</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Chain of search results, represented by pointer to an  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbf"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>The number of <olink targetptr="bdaly">LDAPMessage</olink> structures
in a chain of search results, if successful. If there are no structures, returns
 <literal>0</literal>.</para></listitem>
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
connection handle.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garav"><title>Description</title>
<para>The <function>ldap_count_messages</function> function returns the number
of <olink targetptr="bdaly">LDAPMessage</olink> structures in a chain of search
results. The count is the number of search entries plus the number of search
references.</para>
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in the middle of the chain of results, the function counts only between that
structure and the last structure in the chain. In this type of situation,
the function does not return the count of all structures in the chain.</para>
</note>
</sect3>
<sect3 id="garas"><title>Example</title>
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
<sect3 id="garat"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdarz">ldap_first_message</olink>, <olink targetptr="bdaud">ldap_next_message
</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry</olink> , <olink targetptr="bdasa">ldap_first_reference
</olink>,  <olink targetptr="bdaue">ldap_next_reference</olink></para></sect3>
</sect2>
<sect2 id="bdaqw"><title><function>ldap_count_references</function></title>
<para>The <function>ldap_count_references</function> function returns the
number of <olink targetptr="bdaly">LDAPMessage</olink> structures representing
search references in a chain of search results.</para>
<sect3 id="garaz"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_count_references( LDAP *ld, LDAPMessage *res );</programlisting>
</sect3>
<sect3 id="garam"><title>Parameters</title>
<table frame="topbot" id="garbm"><title><function>ldap_count_references</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Chain of search results, represented by pointer to an  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garab"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>The number of <olink targetptr="bdaly">LDAPMessage</olink> structures
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> in a chain of search
results, if successful. (If there are no structures of this type, returns <literal>
0</literal>.)</para></listitem>
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
connection handle.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garay"><title>Description</title>
<para>The <function>ldap_count_references</function> function returns the
number of <olink targetptr="bdaly">LDAPMessage</olink> structures representing
search references in a chain of search results. These messages have the type <literal>
LDAP_RES_SEARCH_REFERENCE</literal>, continuation references as specified
in LDAPv3 that are stored as referral entries. Like a referral, each continuation
reference itself may contain a number of URLs assumed to be equivalent, and
the client should use one of those URLs.</para>
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in the middle of the chain of results, the function counts only the references
between that structure and the last structure in the chain. In this type of
situation, the function does not return the count of all references in the
chain.</para></note>
</sect3>
<sect3 id="garan"><title>Example</title>
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
<sect3 id="garax"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdasa">ldap_first_reference</olink>, <olink targetptr="bdaue">ldap_next_reference
</olink></para></sect3>
</sect2>
<sect2 id="bdaqx"><title><function>ldap_count_values</function></title>
<para>The <function>ldap_count_values</function> function returns the number
of values in an array of strings.</para>
<note><para>Use the <olink targetptr="bdaqy">ldap_count_values_len</olink> function
if the array contains <olink targetptr="bdakg">berval</olink> structures.</para>
</note>
<sect3 id="garbd"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_count_values( char **values );</programlisting>
</sect3>
<sect3 id="garbp"><title>Parameters</title>
<table frame="topbot" id="garbb"><title><function>ldap_count_values</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><parameter>values</parameter></para></entry>
<entry>
<para>Array of values.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbc"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>The number of values in the array, if successful.</para>
</listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garbk"><title>Example</title>
<para><olink targetptr="ldap-count-values-example">Example 21&ndash;8</olink> counts
the number of values assigned to an attribute.</para>
<example id="ldap-count-values-example"><title>Using <function>ldap_count_values</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *e;
char *a="cn";
char **vals;
int count;
...

/* Get the values of the cn attribute */
vals = ldap_get_values( ld, e, a );

/* Count the values of the attribute */
count = ldap_count_values( vals );
...</programlisting>
</example>
</sect3>
<sect3 id="garak"><title>See Also</title>
<para><olink targetptr="bdaqy">ldap_count_values_len</olink>,  <olink targetptr="bdast">ldap_get_values</olink></para></sect3>
</sect2>
<sect2 id="bdaqy"><title><function>ldap_count_values_len</function></title>
<para>The <function>ldap_count_values_len</function> function returns the
number of values in an array of <olink targetptr="bdakg">berval</olink> structures.
</para>
<note><para>Use the <olink targetptr="bdaqx">ldap_count_values</olink> function
if the array contains strings.</para></note>
<sect3 id="garaw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_count_values_len( struct berval **vals );</programlisting>
</sect3>
<sect3 id="garah"><title>Parameters</title>
<table frame="topbot" id="garbr"><title><function>ldap_count_values_len</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>values</literal></para></entry>
<entry>
<para>Array of <olink targetptr="bdakg">berval</olink> structures.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garal"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>The number of values in the array, if successful.</para>
</listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garaj"><title>Example</title>
<para><olink targetptr="ldap-count-values-len-example">Example 21&ndash;9</olink> 
counts the number of values assigned to an attribute.</para>
<example id="ldap-count-values-len-example"><title>Using <function>ldap_count_values_len
</function></title>
<programlisting>#include &lt;ldap.h>
LDAP *ld;
LDAPMessage *e;
char *a="jpegPhoto";
struct berval **bvals;
int count;
...
/* Get the values of the jpegPhoto attribute */
bvals = ldap_get_values_len( ld, e, a );

/* Count the values of the attribute */
count = ldap_count_values_len( vals );
...</programlisting>
</example>
</sect3>
<sect3 id="garac"><title>See Also</title>
<para><olink targetptr="bdaqx">ldap_count_values</olink>,  <olink targetptr="bdasu">ldap_get_values_len</olink></para></sect3>
</sect2>
<sect2 id="ldap-create-authzid-control"><title><function>ldap_create_authzid_control
</function></title>
<para>The <function>ldap_create_authzid_control</function> function creates
a control that requests the authorization ID for a bind operation. This is
defined in RFC 3829.</para>
<note><para>In order for the control to work, the LDAP server that you are
connecting to must support the server controls for authorization bind identity
(OID <literal>2.16.840.1.113730.3.4.16</literal> or <literal>LDAP_CONTROL_AUTHZID_REQ
</literal>, and OID <literal>2.16.840.1.113730.3.4.15</literal> or <literal>LDAP_CONTROL_AUTHZID_RES
</literal>).</para></note>
<para>Calling <function>ldap_create_authzid_control</function> creates an
LDAP control that you can pass to the <olink targetptr="bdavi">ldap_simple_bind</olink> function
to retrieve the authorization ID in the response. You call <olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink> function
on the controls returned with an entry to retrieve a <literal>char *</literal> containing
the authorization ID.</para>
<para>When you are done with the search, you should free the control by calling
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld,
    const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgbu"><title><function>ldap_create_authzid_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctl_iscritical</parameter></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode> error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink></para>
</sect3>
</sect2>
<sect2 id="bdaqz"><title><function>ldap_create_filter</function></title>
<para>The <function>ldap_create_filter</function> routine constructs an LDAP
search filter.</para>
<sect3 id="garau"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_create_filter( char *buf, unsigned long buflen,
     char *pattern, char *prefix, char *suffix, char *attr,
    char *value, char **valwords );</programlisting>
</sect3>
<sect3 id="garae"><title>Parameters</title>
<table frame="topbot" id="garao"><title><function>ldap_create_filter</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>Buffer to contain the constructed filter.</para></entry>
</row>
<row>
<entry>
<para><literal>buflen</literal></para></entry>
<entry>
<para>Size of the buffer.</para></entry>
</row>
<row>
<entry>
<para><literal>pattern</literal></para></entry>
<entry>
<para>Pattern for the filter.</para></entry>
</row>
<row>
<entry>
<para><literal>prefix</literal></para></entry>
<entry>
<para>Prefix to prepend to the filter. (<literal>NULL</literal> if not used.)</para>
</entry>
</row>
<row>
<entry>
<para><literal>suffix</literal></para></entry>
<entry>
<para>Suffix to append to the filter. (<literal>NULL</literal> if not used.)</para>
</entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Replaces <literal>%a</literal> in the pattern.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Replaces <literal>%v</literal> in the pattern.</para></entry>
</row>
<row>
<entry>
<para><literal>valwords</literal></para></entry>
<entry>
<para>Replaces <literal>%vM</literal> through <literal>%vN</literal> in the
pattern.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the created
filter exceeds the size of the buffer.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garaa"><title>Example</title>
<para><olink targetptr="ldap-create-filter-example">Example 21&ndash;10</olink> builds
the filter <literal>(mail=bjensen@example.com)</literal>.</para>
<example id="ldap-create-filter-example"><title>Creating a Filter with <function>
ldap_create_filter</function></title>
<programlisting>char buf[LDAP_FILT_MAXSIZ];
char *pattern = "(%a=%v)";
char *attr = "mail";
char *value = "bjensen@example.com";
...
ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL,
  NULL, attr, value, NULL );
...</programlisting>
</example>
</sect3>
<sect3 id="garbq"><title>See Also</title>
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>,  <olink targetptr="bdasx">ldap_init_getfilter_buf</olink>, <olink targetptr="bdasn">ldap_getfirstfilter
</olink> , <olink targetptr="bdasr">ldap_getnextfilter</olink>,  <olink targetptr="bdavd">ldap_set_filter_additions</olink></para></sect3>
</sect2>
<sect2 id="bdarb"><title><function>ldap_create_geteffectiveRights_control</function></title>
<para>The <function>ldap_create_geteffectiveRights_control</function> function
allows a user having correct privileges to query about the access rights another
identity has on one or more entries in the directory.</para>
<sect3 id="garap"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_geteffectiveRights_control( LDAP *ld,
    const char *authzid, const char **attrlist, const char ctl_iscritical,
    LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3 id="garbg"><title>Parameters</title>
<table frame="topbot" id="garar"><title><function>ldap_create_geteffectiveRights_control
</function> Function Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="25*"><colspec colnum="2"
colwidth="75*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>authzid</literal></para></entry>
<entry>
<para>The DN of the identity for which you are checking access rights.</para>
</entry>
</row>
<row>
<entry>
<para><literal>attrlist</literal></para></entry>
<entry>
<para>List of attributes to return, such as <literal>aclRights</literal> and <literal>
aclRightsInfo</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>ctl_iscritical</literal></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode> error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdara"><title><function>ldap_create_persistentsearch_control</function></title>
<para>The <function>ldap_create_persistentsearch_control</function> function
creates a control that allows your client to perform a search of an LDAP v3
server that continues without termination until your client abandons it.</para>
<note><para>Persistent search is an optional feature; it may not be supported
on all LDAP servers. In order for the control to work, the server that you
are connecting to must support the server control for persistent searches
(OID 2.16.840.1.113730.3.4.3, or <literal>LDAP_CONTROL_PERSISTENTSEARCH</literal>,
as defined in the <literal>ldap.h</literal>  header file).</para></note>
<sect3 id="garai"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_create_persistentsearch_control( LDAP *ld,
    int changetypes, int changesonly, int return_echg_ctls,
     char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3 id="garaq"><title>Parameters</title>
<table frame="topbot" id="garad"><title><function>ldap_create_persistentsearch_control
</function> Function Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
colwidth="70*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>changetypes</literal></para></entry>
<entry>
<para>Specifies the types of changes that you want to keep track of. This
field can have one or more of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_CHANGETYPE_ADD</literal> specifies that you
want to keep track of entries added to the directory.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_DELETE</literal> specifies that you
want to keep track of entries deleted from the directory.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_MODIFY</literal> specifies that you
want to keep track of entries that are modified.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_MODDN</literal> specifies that you
want to keep track of entries that are renamed.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_ANY</literal> specifies that you
want to keep track of all of the above changes to the directory.</para><para>You
can  <literal>OR</literal> the values together to specify multiple types.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>changesonly</literal></para></entry>
<entry>
<para>Specifies whether or not you want skip the initial search and only get
the latest changes as they occur:</para>
<itemizedlist>
<listitem><para>If non-zero, the initial search is skipped and only entries
that have changed after the initial search are returned.</para></listitem>
<listitem><para>If <literal>0</literal>, the results of the initial search
are returned first.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>return_echg_ctls</literal></para></entry>
<entry>
<para>Specifies whether or not entry controls are included with each entry
returned to your client:</para>
<itemizedlist>
<listitem><para>If non-zero, a control is included with each entry.</para>
</listitem>
<listitem><para>If <literal>0</literal>, controls are not included with the
entries returned from the server.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>ctl_iscritical</literal></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server will return an <literal>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</literal>  error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbi"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garbh"><title>Description</title>
<para>The <function>ldap_create_persistentsearch_control</function> function
allows you to perform persistent searches. A <emphasis>persistent search</emphasis> provides
the means to track changes to a set of entries that match the search criteria.
After the initial search is performed, the server keeps track of the search
criteria and sends back information when any entry that matches the criteria
is added, deleted, modified, or renamed. Calling <function>ldap_create_persistentsearch_control
</function> creates an LDAP server control that you can pass to the <olink targetptr="bdauz">ldap_search_ext</olink>  function.</para>
<para>As stated, after you create the control, you can pass it to the LDAP
server during a search operation. If you specify that you want &ldquo;entry
change notification&rdquo; controls sent back (that is, if you specify a non-zero
value for the <literal>return_echg_ctls</literal>  parameter), the server
includes controls with each changed entry it sends back. To retrieve the controls
from each entry, call the  <olink targetptr="bdasl">ldap_get_entry_controls</olink> function.
To get data about the changes made to the entry from the control, call the <olink targetptr="bdauk">ldap_parse_entrychange_control</olink>  function.</para>
<para>When you are done with the search, you can cancel the persistent search
by calling the <olink targetptr="bdapy">ldap_abandon_ext</olink> function.
You should also free the control from memory by calling the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para></sect3>
<sect3 id="garba"><title>See Also</title>
<para><olink targetptr="bdauz">ldap_search_ext</olink>,  <olink targetptr="bdapy">
ldap_abandon_ext</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink>, <olink targetptr="bdauk">ldap_parse_entrychange_control</olink>,  <olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
</sect2>
<sect2 id="ldap-create-pwdpolicy-control"><title><function>ldap_create_pwdpolicy_control
</function></title>
<para>The <function>ldap_create_pwdpolicy_control</function> function creates
a control that requests information about the status of a user account.</para>
<note><para><function>ldap_create_pwdpolicy_control</function> implements
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para><para>In
order for the control to work, the LDAP server that you are connecting to
must support the server control for password policy (OID <literal>1.3.6.1.4.1.42.2.27.8.5.1
</literal>, or <literal>LDAP_CONTROL_ACCOUNT_USABLE</literal>).</para></note>
<para>Calling <function>ldap_create_pwdpolicy_control</function> creates an
LDAP control that you can pass to the <olink targetptr="bdavi">ldap_simple_bind</olink> functions
to retrieve password policy information from bind, modify, add, compare, and
potentially extended operation responses including password policy response
controls. You call <olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
</olink> function on the controls returned with an entry to retrieve a <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure containing information
about the status of the account.</para>
<para>When you are done with the search, you should free the control by calling
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_pwdpolicy_control( LDAP *ld,
    const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgby"><title><function>ldap_create_pwdpolicy_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctl_iscritical</parameter></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode> error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
</olink>, <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink></para></sect3>
</sect2>
<sect2 id="bdarc"><title><function>ldap_create_proxiedauth_control</function></title>
<para>The <function>ldap_create_proxiedauth_control</function> function creates
an LDAP v3 control that allows a bound entity to assume the identity of another
directory entry.</para>
<note><para><olink targetptr="bdarc">ldap_create_proxiedauth_control</olink> is
a new version of the <olink targetptr="bdard">ldap_create_proxyauth_control</olink> function.
If you are writing a new LDAP client, use <olink targetptr="bdarc">ldap_create_proxiedauth_control
</olink> .</para></note>
<sect3 id="gardl"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
     LDAPControl **ctrlp);</programlisting>
</sect3>
<sect3 id="gardm"><title>Parameters</title>
<table frame="topbot" id="garcl"><title><function>ldap_create_proxiedauth_control
</function> Function Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="25*"><colspec colnum="2"
colwidth="75*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>authzid</literal></para></entry>
<entry>
<para>The string representing the identity to assume for the access rights,
defined in the format specified by the following Augmented Backus-Naur Form
(ABNF) from RFC 4513:</para>
<programlisting>; Specific predefined authorization (authz)
; id schemes are defined below --
; new schemes may be defined in the future.

authzId   = dnAuthzId / uAuthzId

; distinguished-name-based authz id.
dnAuthzId = "dn:" dn
dn        = utf8string    ; syntax from RFC 4514

; unspecified userid, UTF-8 encoded.
uAuthzId  = "u:" userid
userid    = utf8string    ; syntax unspecified</programlisting>
</entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garcz"><title>Description</title>
<para>More information on proxy authorization can be found in the <citetitle> LDAP
Proxied Authorization Control Internet Draft</citetitle> (<ulink
url="http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt"
type="text_url"></ulink>).</para>
<note><para>Proxy authorization is an optional feature; it may not be supported
on all LDAP servers. In order for the control to work, the server that you
are connecting to must support the server control for proxy authorization
(OID 2.16.840.1.113730.3.4.18, or <literal>LDAP_CONTROL_PROXIEDAUTH</literal>,
as defined in the <literal>ldap-extension.h</literal>  header file).</para>
</note>
</sect3>
</sect2>
<sect2 id="bdard"><title><function>ldap_create_proxyauth_control</function></title>
<para>The <function>ldap_create_proxyauth_control</function> function creates
an LDAP v3 control that allows a bound entity to assume the identity of another
directory entry.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdarc">ldap_create_proxiedauth_control
</olink> .</para></note>
<sect3 id="garcp"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_create_proxyauth_control( LDAP *ld, char *DN,
     char ctl_iscritical, LDAPControl **ctrlp);</programlisting>
</sect3>
<sect3 id="garcw"><title>Parameters</title>
<table frame="topbot" id="garby"><title><function>ldap_create_proxyauth_control</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
colwidth="70*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>DN</literal></para></entry>
<entry>
<para>String representing the DN of the entry who's identity the client will
be assuming.</para></entry>
</row>
<row>
<entry>
<para><literal>ctl_iscritical</literal></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode>  error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gardo"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION</errorcode> if
the server does not support proxy authorization and <literal>ctl_iscritical</literal> is
set to a non-zero value.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gardd"><title>See Also</title>
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
</sect2>
<sect2 id="bdare"><title><function>ldap_create_sort_control</function></title>
<para>The <function>ldap_create_sort_control</function> function creates a
control that specifies the order in which you want search results returned.</para>
<note><para>This function implements an extension to the LDAP v3. Server-side
sorting is an optional feature; it may not be supported on all LDAP servers.
Call this function when interacting with LDAP servers that support this LDAP
v3 extension.</para></note>
<sect3 id="garcu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_create_sort_control( LDAP *ld,
     LDAPsortkey **sortKeyList, const char ctl_iscritical,
     LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3 id="gardg"><title>Parameters</title>
<table frame="topbot" id="gardi"><title><function>ldap_create_sort_control</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
colwidth="70*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>sortKeyList</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
that specify the attribute types or matching rules used for sorting and the
order (ascending or descending) in which to sort the results.</para></entry>
</row>
<row>
<entry>
<para><literal>ctl_iscritical</literal></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode> error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gardf"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garce"><title>Description</title>
<para>The <function>ldap_create_sort_control</function> function allows you
to specify the order in which you want to receive data from the server. Calling
this function creates an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext</olink>  and <olink targetptr="bdava">ldap_search_ext_s
</olink> functions.</para>
<note><para>In order for the control to work, the LDAP server that you are
connecting to must support the server control for sorting search results (OID
1.2.840.113556.1.4.473, or <literal>LDAP_CONTROL_SORTREQUEST</literal>, as
defined in the <literal>ldap.h</literal>  header file).</para></note>
<para>To specify the attributes to use for sorting the results, you can call <olink targetptr="bdarf">ldap_create_sort_keylist</olink> to create an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures and pass the array as the
 <literal>sortKeyList</literal> argument. When you are done with the search,
you should free the control and the array of <olink targetptr="bdamc">LDAPsortkey
</olink> structures by calling the <olink targetptr="bdaqs">ldap_control_free</olink> and
 <olink targetptr="bdasg">ldap_free_sort_keylist</olink> functions.</para>
</sect3>
<sect3 id="gardp"><title>See Also</title>
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>,  <olink targetptr="bdauz">ldap_search_ext</olink>, <olink targetptr="bdava">ldap_search_ext_s
</olink>, <olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
</sect2>
<sect2 id="bdarf"><title><function>ldap_create_sort_keylist</function></title>
<para>The <function>ldap_create_sort_keylist</function> function creates an
array of <olink targetptr="bdamc">LDAPsortkey</olink> structures from a string
representation of a set of sort keys.</para>
<sect3 id="garbs"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
     const char *string_rep);</programlisting>
</sect3>
<sect3 id="gardn"><title>Parameters</title>
<table frame="topbot" id="garcv"><title><function>ldap_create_sort_keylist</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sortKeyList</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
that specify the attribute types or matching rules used for sorting and the
order (ascending or descending) in which to sort the results.</para></entry>
</row>
<row>
<entry>
<para><literal>string_rep</literal></para></entry>
<entry>
<para>String representation of a set of sort keys. The value should specify
the name of the attribute that you want to sort by. To sort in reverse order,
precede the attribute name with a hyphen, <literal>-</literal>. To use a matching
rule for sorting, append a colon to the attribute name and specify the object
identifier (OID) of a matching rule after the colon. For example:</para>
<orderedlist>
<listitem><para><literal>cn</literal> (sorts by the <literal>cn</literal> attribute)
</para></listitem>
<listitem><para><literal>-cn</literal> (sorts by the <literal>cn</literal> attribute
in reverse order)</para></listitem>
<listitem><para><literal>-cn:1.2.3.4</literal> (sorts by the <literal>cn</literal> attribute
in reverse order using the matching rule identified by the OID <literal>1.2.3.4</literal>)
</para></listitem>
</orderedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbu"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><literal>-1</literal> if an error occurred.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garda"><title>Description</title>
<para>Calling the <function>ldap_create_sort_keylist</function> function allows
you to create an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
from a string representation of a set of sort keys. You can then pass the
array to the <olink targetptr="bdare">ldap_create_sort_control</olink> function.
The string representation specified by the <literal>string_rep</literal> argument
should specify the name of the attribute that you want to sort by and how
the sort will work. When you are done sorting the results, you should free
the array of <olink targetptr="bdamc">LDAPsortkey</olink>  structures by calling
the <olink targetptr="bdasg">ldap_free_sort_keylist</olink>  function.</para>
</sect3>
<sect3 id="garbw"><title>See Also</title>
<para><olink targetptr="bdare">ldap_create_sort_control</olink>,  <olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></sect3>
</sect2>
<sect2 id="ldap-create-userstatus-control"><title><function>ldap_create_userstatus_control
</function></title>
<para>The <function>ldap_create_userstatus_control</function> function creates
a control that requests information about the status of a user account.</para>
<note><para><function>ldap_create_userstatus_control</function> implements
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para><para>In
order for the control to work, the LDAP server that you are connecting to
must support the server control for account availability (OID <literal>1.3.6.1.4.1.42.2.27.9.5.8
</literal>, or <literal>LDAP_CONTROL_ACCOUNT_USABLE</literal>).</para></note>
<para>Calling <function>ldap_create_userstatus_control</function> creates
an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext
</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink> functions.
You call <olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
</olink> function on the controls returned with an entry to retrieve a <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure containing information
about the status of the account.</para>
<para>When you are done with the search, you should free the control by calling
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld,
    const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgbt"><title><function>ldap_create_userstatus_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctl_iscritical</parameter></para></entry>
<entry>
<para>Specifies whether the control is critical to the operation.</para>
<itemizedlist>
<listitem><para>If non-zero, the control is critical to the operation. If
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
</errorcode> error.</para></listitem>
<listitem><para>If <literal>0</literal>, the control is not critical to the
operation. Even if the server does not support the control, the operation
is still attempted and the control is ignored.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
</olink>, <olink targetptr="ldapuserstatus">LDAPuserstatus</olink></para>
</sect3>
</sect2>
<sect2 id="bdarg"><title><function>ldap_create_virtuallist_control</function></title>
<para>The <function>ldap_create_virtuallist_control</function> function creates
a control that requests a subset of search results for use in a virtual list
box.</para>
<note><para><function>ldap_create_virtuallist_control</function> implements
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para></note>
<sect3 id="garbx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_create_virtuallist_control( LDAP *ld,
     LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );</programlisting>
</sect3>
<sect3 id="garde"><title>Parameters</title>
<table frame="topbot" id="garci"><title><function>ldap_create_virtuallist_control
</function> Function Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>ldvlistp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdamv">LDAPVirtualList</olink> structure
that specifies the subset of entries that you want retrieved from the server
and the selected entry.</para></entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
created by this function. When you are done using this control, you should
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garbz"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garco"><title>Description</title>
<para>The <function>ldap_create_virtuallist_control</function> function allows
you to retrieve a subset of entries from the server for use in a virtual list
box. To specify the subset of entries that you want to retrieve, create an
 <olink targetptr="bdamv">LDAPVirtualList</olink> structure and pass in a
pointer to this structure as the  <literal>ldvlistp</literal> argument.</para>
<note><para>In order for the control to work, the LDAP server that you are
connecting to must support the server control for sorting search results (OID
2.16.840.1.113730.3.4.9, or <literal>LDAP_CONTROL_VLVREQUEST</literal>, as
defined in the <literal>ldap.h</literal> header file).</para></note>
<para>Calling <function>ldap_create_virtuallist_control</function> creates
an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext
</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink> functions.
You also need to pass a server-side sorting control to the search functions.
You can call <olink targetptr="bdarf">ldap_create_sort_keylist</olink>  and <olink targetptr="bdare">ldap_create_sort_control</olink> to create a server-side
sorting control. When you are done with the search, you should free the control
by calling the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
</sect3>
<sect3 id="garcd"><title>See Also</title>
<para><olink targetptr="bdamv">LDAPVirtualList</olink>,  <olink targetptr="bdauq">
ldap_parse_virtuallist_control</olink>, <olink targetptr="bdauz">ldap_search_ext</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdaqs">ldap_control_free
</olink></para></sect3>
</sect2>
<sect2 id="bdarh"><title><function>ldap_delete</function></title>
<para>The <function>ldap_delete</function> function removes an entry from
the directory asynchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdari">ldap_delete_ext
</olink>  instead.</para></note>
<sect3 id="garbv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_delete( LDAP *ld, const char *dn );</programlisting>
</sect3>
<sect3 id="garcf"><title>Parameters</title>
<table frame="topbot" id="garcb"><title><function>ldap_delete</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to remove.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garcq"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_delete</function> operation.</para>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
See <olink targetptr="bdarj">ldap_delete_ext_s</olink> for a list of possible
result codes for the LDAP delete operation.</para></note>
</sect3>
<sect3 id="gardc"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdari">ldap_delete_ext
</olink> .</para></sect3>
<sect3 id="garch"><title>Example</title>
<para><olink targetptr="ldap-delete-example">Example 21&ndash;11</olink> uses
the asynchronous <function>ldap_delete</function> function to remove the entry
for  <literal>Barbara Jensen</literal> from the directory.</para>
<example id="ldap-delete-example"><title>Using <function>ldap_delete</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the entry that you want to delete. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
...
/* Set up the timeout period to wait for the "modify" operation */
tv.tv_sec = tv.tv_usec = 0;

/* Delete the entry */
if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) {
  ldap_perror( ld, "ldap_delete" );
  return( 1 );
}
/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &amp;tv, &amp;result ) ) == 0 ) {
  ...
  /* do other work while waiting for the operation to complete */
  ...
}
/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_delete" );
...</programlisting>
</example>
</sect3>
<sect3 id="garcg"><title>See Also</title>
<para><olink targetptr="bdari">ldap_delete_ext</olink></para></sect3>
</sect2>
<sect2 id="bdari"><title><function>ldap_delete_ext</function></title>
<para>The <function>ldap_delete_ext</function> function deletes an entry from
the directory asynchronously.</para>
<note><para><function>ldap_delete_ext</function> is a new version of the  <olink targetptr="bdarh">ldap_delete</olink> function. If you are writing a new LDAP
client, you should call <olink targetptr="bdari">ldap_delete_ext</olink>.</para>
</note>
<sect3 id="garcs"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_delete_ext( LDAP *ld, const char *dn,
    LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );</programlisting>
</sect3>
<sect3 id="garck"><title>Parameters</title>
<table frame="topbot" id="gardb"><title><function>ldap_delete_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to remove.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garcx"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
See <olink targetptr="bdarj">ldap_delete_ext_s</olink> for a list of possible
result codes for the LDAP delete operation.</para></note>
</sect3>
<sect3 id="garcn"><title>Description</title>
<para>The <function>ldap_delete_ext</function> function deletes an entry from
the directory, using the <literal>dn</literal> argument to specify the entry
that you want to delete. <function>ldap_delete_ext</function> is an asynchronous
function; it does not directly return results. If you want the results to
be returned directly by the function, call the synchronous function <olink targetptr="bdarj">ldap_delete_ext_s</olink> .</para></sect3>
<sect3 id="garbt"><title>See Also</title>
<para><olink targetptr="bdarj">ldap_delete_ext_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
</olink></para></sect3>
</sect2>
<sect2 id="bdarj"><title><function>ldap_delete_ext_s</function></title>
<para>The <function>ldap_delete_ext_s</function> function deletes an entry
from the directory synchronously.</para>
<note><para><function>ldap_delete_ext_s</function> is a new version of the <olink targetptr="bdark">ldap_delete_s</olink> function. If you are writing a new
LDAP client, you should call <function>ldap_delete_ext_s</function>.</para>
</note>
<sect3 id="gardj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_delete_ext_s( LDAP *ld, const char *dn,
     LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="gardk"><title>Parameters</title>
<table frame="topbot" id="garct"><title><function>ldap_delete_ext_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to remove.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garca"><title>Returns</title>
<para>One of the following values:</para></sect3>
<sect3 id="garcr"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garcc"><title>Description</title>
<para>The <function>ldap_delete_ext_s</function> function deletes an entry
from the directory, using the <literal>dn</literal> argument to specify the
entry that you want to delete. <function>ldap_delete_ext_s</function> is a
synchronous function, which directly returns the results of the operation.
If you want to perform other operations while waiting for the results of this
operation, call the asynchronous function <olink targetptr="bdari">ldap_delete_ext
</olink> instead.</para></sect3>
<sect3 id="garcy"><title>See Also</title>
<para><olink targetptr="bdari">ldap_delete_ext</olink></para></sect3>
</sect2>
<sect2 id="bdark"><title><function>ldap_delete_s</function></title>
<para>The <function>ldap_delete_s</function> deletes an entry from the directory
synchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdarj">ldap_delete_ext_s
</olink>  instead.</para></note>
<sect3 id="garcj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_delete_s(LDAP *ld, const char *dn);</programlisting>
</sect3>
<sect3 id="garcm"><title>Parameters</title>
<table frame="topbot" id="gareg"><title><function>ldap_delete_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to remove.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garfc"><title>Returns</title>
<para>For a list of possible result codes for an LDAP delete operation, see
the <olink targetptr="bdarj">ldap_delete_ext_s</olink> function.</para></sect3>
<sect3 id="garfj"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdarj">ldap_delete_ext_s
</olink> .</para></sect3>
<sect3 id="garex"><title>Example</title>
<para><olink targetptr="ldap-delete-s-example">Example 21&ndash;12</olink> uses
the synchronous <function>ldap_delete_s</function> function to delete the
entry for  <literal>Barbara Jensen</literal> from the directory.</para>
<example id="ldap-delete-s-example"><title>Using <function>ldap_delete_s</function></title>
<programlisting>#include &lt;ldap.h>
LDAP *ld;

/* Distinguished name of the entry that you want to delete. */
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
...
/* Delete the entry */
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_delete_s" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garfg"><title>See Also</title>
<para><olink targetptr="bdarj">ldap_delete_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdarl"><title><function>ldap_dn2ufn</function></title>
<para>The <function>ldap_dn2ufn</function> function converts a DN into a more
user-friendly form by stripping off the cryptic type names.</para>
<sect3 id="garet"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char * ldap_dn2ufn( const char *dn );</programlisting>
</sect3>
<sect3 id="garfd"><title>Parameters</title>
<table frame="topbot" id="garei"><title><function>ldap_dn2ufn</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>The DN that you want converted.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garer"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the DN in its friendlier form.</para>
</listitem>
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garew"><title>Description</title>
<para>For more information on user friendly naming (UFN), see RFC 1781,<citetitle>
 Using the OSI Directory to Achieve User Friendly Naming </citetitle> (<ulink
url="http://www.faqs.org/rfcs/rfc1781.html" type="text_url"></ulink>).</para>
</sect3>
</sect2>
<sect2 id="bdarm"><title><function>ldap_entry2html</function></title>
<para>The <function>ldap_entry2html</function> function writes the HTML representation
of an LDAP entry.</para>
<sect3 id="garek"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
    struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
    writeptype writeproc, void *writeparm, char *eol, int rdncount,
    unsigned long opts, char *urlprefix, char *base );</programlisting>
</sect3>
<sect3 id="garef"><title>Parameters</title>
<table frame="topbot" id="garfi"><title><function>ldap_entry2html</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>A pointer to a buffer of size <literal>LDAP_DTMPL_BUFSIZ</literal> or
larger. If <literal>NULL</literal>, a buffer is allocated and freed internally.</para>
</entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Specifies the attribute values to be represented.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>Pointer to the display template to be used, usually obtained by calling <olink targetptr="bdaui">ldap_oc2template</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>defattrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
which you wish to provide default values. It is only used if the entry contains
no values for the attribute.</para></entry>
</row>
<row>
<entry>
<para><literal>defvals</literal></para></entry>
<entry>
<para>An array of <literal>NULL</literal> terminated arrays of default values
corresponding to the attributes.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para>Your <function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
<row>
<entry>
<para><literal>opts</literal></para></entry>
<entry>
<para>Specifies output options. The allowed values are:</para>
<itemizedlist>
<listitem><para>zero (default output)</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
the width for labels to be determined based on the longest label in <literal>tmpl
</literal>.</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
the library not to include  <literal>&lt;HTML></literal>,  <literal>&lt;HEAD></literal>,
 <literal>&lt;TITLE></literal>, and <literal>&lt;BODY></literal> tags. In
other words, an HTML fragment is generated, and the caller is responsible
for prepending and appending the appropriate HTML tags to construct a correct
HTML document.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>urlprefix</literal></para></entry>
<entry>
<para>Starting text to use  when constructing  an LDAP URL. The default is
the string  <literal>ldap://</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>The base with which to begin when executing search actions. If <literal>NULL
</literal> , search action template items are ignored.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gards"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gardt"><title>Description</title>
<para><function>ldap_entry2html</function> produces an HTML representation
of an entry. It  behaves exactly like <olink targetptr="bdaro">ldap_entry2text</olink> except
for the output and the addition of two parameters.</para></sect3>
<sect3 id="garfa"><title>See Also</title>
<para><olink targetptr="bdaro">ldap_entry2text</olink>,  <olink targetptr="bdaui">
ldap_oc2template</olink></para></sect3>
</sect2>
<sect2 id="bdarn"><title><function>ldap_entry2html_search</function></title>
<para>The <function>ldap_entry2html_search</function> function determines
the appropriate display template to use by calling <olink targetptr="bdaui">ldap_oc2template
</olink>.</para>
<sect3 id="gareb"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_entry2html_search( LDAP *ld, char *dn, char *base,
    LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
    char ***defvals, writeptype writeproc, void *writeparm, char *eol,
    int rdncount, unsigned long opts, char *urlprefix );</programlisting>
</sect3>
<sect3 id="garez"><title>Parameters</title>
<table frame="topbot" id="garem"><title><function>ldap_entry2html_search</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to write as HTML.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>The base with which to begin when executing search actions. If <literal>NULL
</literal> , search action template items are ignored.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Specifies the attribute values to be represented.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllist</literal></para></entry>
<entry>
<para>Pointer to the entire list of templates available, usually obtained
by calling <olink targetptr="bdata">ldap_init_templates</olink> or <olink targetptr="bdatb">ldap_init_templates_buf</olink>. If <literal>NULL</literal>,
will attempt to read a load templates from the default template configuration
file.</para></entry>
</row>
<row>
<entry>
<para><literal>defattrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
which you wish to provide default values. It is only used if the entry contains
no values for the attribute.</para></entry>
</row>
<row>
<entry>
<para><literal>defvals</literal></para></entry>
<entry>
<para>An array of <literal>NULL</literal> terminated arrays of default values
corresponding to the attributes.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para><function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
<row>
<entry>
<para><literal>opts</literal></para></entry>
<entry>
<para>Specifies output options. The allowed values are:</para>
<itemizedlist>
<listitem><para>zero (default   output)</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
the width for labels to be determined based on the longest label in <literal>tmpl
</literal>.</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
the library not to include  <literal>&lt;HTML></literal>,  <literal>&lt;HEAD></literal>,
 <literal>&lt;TITLE></literal>, and <literal>&lt;BODY></literal> tags. In
other words, an HTML fragment is generated, and the caller is responsible
for prepending and appending the appropriate HTML tags to construct a correct
HTML document.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>urlprefix</literal></para></entry>
<entry>
<para>Starting text to use  when constructing  an LDAP URL. The  default 
is  the string <literal>ldap://</literal></para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gares"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garfn"><title>Description</title>
<para><function>ldap_entry2html_search</function> will call  <olink targetptr="bdavb">ldap_search_s</olink> to retrieve any attribute values to
be displayed. It behaves exactly like <olink targetptr="bdarp">ldap_entry2text_search
</olink>, except the  <literal>urlprefix</literal> parameter is required and
HTML is the output.</para></sect3>
<sect3 id="gardu"><title>See Also</title>
<para><olink targetptr="bdavb">ldap_search_s</olink>,  <olink targetptr="bdarp">ldap_entry2text_search
</olink>, <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf</olink>, <olink targetptr="bdaro">ldap_entry2text
</olink></para></sect3>
</sect2>
<sect2 id="bdaro"><title><function>ldap_entry2text</function></title>
<para>The <function>ldap_entry2text</function> function writes the text representation
of an LDAP entry.</para>
<sect3 id="gardz"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_entry2text( LDAP *ld, char *buf, LDAPMessage *entry,
    struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
    writeptype writeproc, void *writeparm, char *eol, int rdncount,
    unsigned long opts );</programlisting>
</sect3>
<sect3 id="garfb"><title>Parameters</title>
<table frame="topbot" id="gardw"><title><function>ldap_entry2text</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>A pointer to a buffer of size <literal>LDAP_DTMPL_BUFSIZ</literal> or
larger. If <literal>NULL</literal>, a buffer is allocated and freed internally.</para>
</entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Specifies the attribute values to be represented.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>Pointer to the display template to be used, usually obtained by calling <olink targetptr="bdaui">ldap_oc2template</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>defattrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
which you wish to provide default values. It is only used if the entry contains
no values for the attribute.</para></entry>
</row>
<row>
<entry>
<para><literal>defvals</literal></para></entry>
<entry>
<para>An array of <literal>NULL</literal> terminated arrays of default values
corresponding to the attributes.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para><function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
<row>
<entry>
<para><literal>opts</literal></para></entry>
<entry>
<para>Specifies output options. The allowed values are:</para>
<itemizedlist>
<listitem><para>zero (default output)</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
the width for labels to be determined based on the longest label in <literal>tmpl
</literal>.</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
the library not to include  <literal>&lt;HTML></literal>,  <literal>&lt;HEAD></literal>,
 <literal>&lt;TITLE></literal>, and <literal>&lt;BODY></literal> tags. In
other words, an HTML fragment is generated, and the caller is responsible
for prepending and appending the appropriate HTML tags to construct a correct
HTML document.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garfh"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gared"><title>Description</title>
<para><function>ldap_entry2text</function> produces a text representation
of an entry and writes the text by calling the <literal>writeproc</literal> function.
All of the attribute values to be displayed must be present in entry as no
interaction with the LDAP server will be performed.</para></sect3>
<sect3 id="garfl"><title>See Also</title>
<para><olink targetptr="bdarm">ldap_entry2html</olink>,  <olink targetptr="bdaui">
ldap_oc2template</olink></para></sect3>
</sect2>
<sect2 id="bdarp"><title><function>ldap_entry2text_search</function></title>
<para>The <function>ldap_entry2text_search</function> function determines
the appropriate display template to use by calling <olink targetptr="bdaui">ldap_oc2template
</olink>.</para>
<sect3 id="garec"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_entry2text_search( LDAP *ld, char *dn, char *base,
    LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
    char ***defvals, writeptype writeproc, void *writeparm,
    char *eol, int rdncount, unsigned long opts );</programlisting>
</sect3>
<sect3 id="gardy"><title>Parameters</title>
<table frame="topbot" id="gareu"><title><function>ldap_entry2text_search</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to write.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>If <literal>NULL</literal>, the search action template items are ignored.
If not <literal>NULL</literal>, it is the search  base to use when executing
search actions.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>If entry is not <literal>NULL</literal>, it should  contain the <literal>objectClass
</literal>  attribute values for the entry to be displayed. If <literal>NULL</literal>, <parameter>
dn</parameter> can not be <literal>NULL</literal>, and <olink targetptr="bdarp">ldap_entry2text_search
</olink>  will retrieve the <literal>objectClass</literal> values itself by
calling <olink targetptr="bdavb">ldap_search_s</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllist</literal></para></entry>
<entry>
<para>Pointer to the entire list of templates available, usually obtained
by calling <olink targetptr="bdata">ldap_init_templates</olink> or <olink targetptr="bdatb">ldap_init_templates_buf</olink>. If <literal>NULL</literal>,
will attempt to read a load templates from the default template configuration
file.</para></entry>
</row>
<row>
<entry>
<para><literal>defattrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
which you wish to provide default values. It is only used if the entry contains
no values for the attribute.</para></entry>
</row>
<row>
<entry>
<para><literal>defvals</literal></para></entry>
<entry>
<para>An array of <literal>NULL</literal> terminated arrays of default values
corresponding to the attributes.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para><function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
<row>
<entry>
<para><literal>opts</literal></para></entry>
<entry>
<para>Specifies output options. The allowed values are:</para>
<itemizedlist>
<listitem><para>zero (default   output)</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
the width for labels to be determined based on the longest label in <literal>tmpl
</literal>.</para></listitem>
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
the library not to include  <literal>&lt;HTML></literal>,  <literal>&lt;HEAD></literal>,
 <literal>&lt;TITLE></literal>, and <literal>&lt;BODY></literal> tags. In
other words, an HTML fragment is generated, and the caller is responsible
for prepending and appending the appropriate HTML tags to construct a correct
HTML document.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garen"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garey"><title>Description</title>
<para><function>ldap_entry2text_search</function> will call  <olink targetptr="bdavb">ldap_search_s</olink> to retrieve any attribute values to
be displayed.</para></sect3>
<sect3 id="gareh"><title>See Also</title>
<para><olink targetptr="bdarn">ldap_entry2html_search</olink>,  <olink targetptr="bdaui">ldap_oc2template</olink>, <olink targetptr="bdavb">ldap_search_s
</olink>, <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf</olink></para></sect3>
</sect2>
<sect2 id="bdarq"><title><function>ldap_err2string</function></title>
<para>The <function>ldap_err2string</function> function returns the corresponding
error message for an error code.</para>
<sect3 id="garep"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char * ldap_err2string( int err );</programlisting>
</sect3>
<sect3 id="gardq"><title>Parameters</title>
<table frame="topbot" id="garff"><title><function>ldap_err2string</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>err</literal></para></entry>
<entry>
<para>Error code that you want interpreted into an error message.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garee"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the corresponding error message for
the error code.</para></listitem>
<listitem><para>If unsuccessful (for example, if the error code is not a valid
LDAP API error code), returns <literal>Unknown error</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garea"><title>Example</title>
<para><olink targetptr="ldap-err2string-example">Example 21&ndash;13</olink> sets
the variable <replaceable>err_msg</replaceable> to the error message corresponding
to the error code returned by the <function>ldap_simple_bind_s</function> function.
</para>
<example id="ldap-err2string-example"><title>Using <function>ldap_err2string</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
char *pw = "hifalutin";
char *err_msg;
...
err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
...</programlisting>
</example>
</sect3>
<sect3 id="gardv"><title>See Also</title>
<para><olink targetptr="bdasq">ldap_get_lderrno</olink>,  <olink targetptr="bdaur">ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error
</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink>, <olink targetptr="bdavr">ldapssl_err2string</olink></para></sect3>
</sect2>
<sect2 id="bdarr"><title><function>ldap_explode_dn</function></title>
<para>The <function>ldap_explode_dn</function> function converts a DN into
its component parts.</para>
<sect3 id="garej"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char ** ldap_explode_dn( const char *dn, int notypes );</programlisting>
</sect3>
<sect3 id="gareo"><title>Parameters</title>
<table frame="topbot" id="garfe"><title><function>ldap_explode_dn</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN that you want separated into components.</para></entry>
</row>
<row>
<entry>
<para><literal>notypes</literal></para></entry>
<entry>
<para>Specifies whether or not type names in the DN are returned. This parameter
can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that type names are returned.</para>
</listitem>
<listitem><para>A non-zero value specifies that type names are not returned.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garfk"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array containing the components of the DN.</para></listitem>
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garev"><title>Example</title>
<para>The following function call:</para>
<programlisting>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 );</programlisting>
<para>returns this array:</para>
<programlisting>{ "uid=bjensen", "ou=People", "dc=example,dc=com", NULL }</programlisting>
<para>If you change the <literal>notypes</literal> parameter from <literal>0</literal> to
 <literal>1</literal>:</para>
<programlisting>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 1 );</programlisting>
<para>The component names are not returned in the array:</para>
<programlisting>{ "bjensen", "People", "example.com", NULL }</programlisting>
</sect3>
<sect3 id="gardr"><title>See Also</title>
<para><olink targetptr="bdart">ldap_explode_rdn</olink>,  <olink targetptr="bdask">ldap_get_dn</olink></para></sect3>
</sect2>
<sect2 id="bdars"><title><function>ldap_explode_dns</function></title>
<note><para>This function is to be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
<para>The <function>ldap_explode_dns</function> function takes a DNS-style
DN, breaks it up into its  component parts, and returns a <literal>NULL</literal> terminated
array. For example, the DN <literal>ldap.example.com</literal> will return <literal>
{ "ldap", "example", "com", NULL }</literal>. The result can be freed by calling
 <olink targetptr="bdaxc">ldap_value_free</olink>.</para>
<sect3 id="garfm"><title>Syntax</title>
<programlisting>#include &lt;ldap-to-be-deprecated.h>
 char ** ldap_explode_dns( const char *dn );</programlisting>
</sect3>
<sect3 id="gareq"><title>Parameters</title>
<table frame="topbot" id="garel"><title><function>ldap_explode_dns</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN that you want separated into components.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gardx"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array containing the components of the DN.</para></listitem>
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdart"><title><function>ldap_explode_rdn</function></title>
<para>The <function>ldap_explode_rdn</function> function converts a relative
distinguished name (RDN) into its component parts.</para>
<sect3 id="gargn"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
char ** ldap_explode_rdn( const char *dn, int notypes );</programlisting>
</sect3>
<sect3 id="garhi"><title>Parameters</title>
<table frame="topbot" id="gargd"><title><function>ldap_explode_rdn</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>RDN that you want separated into components.</para></entry>
</row>
<row>
<entry>
<para><literal>notypes</literal></para></entry>
<entry>
<para>Specifies whether or not type names in the RDN are returned. This parameter
can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that type names are returned.</para>
</listitem>
<listitem><para>A non-zero value specifies that type names are not returned.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhg"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array containing the components of the RDN.</para></listitem>
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gargu"><title>Example</title>
<para>The following function call:</para>
<programlisting>ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );</programlisting>
<para>returns this array:</para>
<programlisting>{ "ou=Sales", "cn=Barbara Jensen", NULL }</programlisting>
</sect3>
<sect3 id="gargt"><title>See Also</title>
<para><olink targetptr="bdarr">ldap_explode_dn</olink>,  <olink targetptr="bdask">
ldap_get_dn</olink></para></sect3>
</sect2>
<sect2 id="bdaru"><title><function>ldap_extended_operation</function></title>
<para>The <function>ldap_extended_operation</function> function sends a request
to the server to perform an extended operation asynchronously.</para>
<sect3 id="gargk"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_extended_operation( LDAP *ld, const char *requestoid,
     struct berval *requestdata, LDAPControl **serverctrls,
     LDAPControl **clientctrls, int *msgidp );</programlisting>
</sect3>
<sect3 id="garhn"><title>Parameters</title>
<table frame="topbot" id="garfr"><title><function>ldap_extended_operation</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>requestoid</literal></para></entry>
<entry>
<para>Object identifier (OID) of the extended operation that you want the
server to perform. After processing an LDAP v3 extended operation, an LDAP
server can return an OID and data in the result. To parse the OID and data
from the result, call the <olink targetptr="bdaul">ldap_parse_extended_result</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>requestdata</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakg">berval</olink> structure containing
the data that you want passed to the server to perform the extended operation.
The data in the <olink targetptr="bdakg">berval</olink> is a buffer of the
BER encoded data type, usually obtained using the <olink targetptr="bdaof">ber_flatten
</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gargy"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink>, <olink targetptr="bdaul">ldap_parse_extended_result</olink>,
and <olink targetptr="bdasq">ldap_get_lderrno</olink>.</para></note>
</sect3>
<sect3 id="garge"><title>Description</title>
<para>The <function>ldap_extended_operation</function> function sends a request
to the server to perform an LDAP v3 extended operation. <function>ldap_extended_operation
</function>  is an asynchronous function; it does not directly return results.
If you want the results to be returned directly by the function, call the
synchronous function <olink targetptr="bdarv">ldap_extended_operation_s</olink>.</para>
</sect3>
<sect3 id="gargi"><title>See Also</title>
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaul">ldap_parse_extended_result
</olink>, <olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdaof">ber_flatten</olink></para></sect3>
</sect2>
<sect2 id="bdarv"><title><function>ldap_extended_operation_s</function></title>
<para>The <function>ldap_extended_operation_s</function> function sends a
request to the server to perform an extended operation synchronously.</para>
<sect3 id="gargg"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
   struct berval *requestdata, LDAPControl **serverctrls,
   LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );</programlisting>
</sect3>
<sect3 id="garfx"><title>Parameters</title>
<table frame="topbot" id="gargo"><title><function>ldap_extended_operation_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>requestoid</literal></para></entry>
<entry>
<para>Object identifier (OID) of the extended operation that you want the
server to perform.</para></entry>
</row>
<row>
<entry>
<para><literal>requestdata</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakg">berval</olink> structure containing
the data that you want passed to the server to perform the extended operation.
The data in the <olink targetptr="bdakg">berval</olink> is a buffer of the
BER encoded data type, usually obtained using the <olink targetptr="bdaof">ber_flatten
</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>retoidp</literal></para></entry>
<entry>
<para>Pointer to the OID returned by the server after performing the extended
operation. When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
</olink>  function.</para></entry>
</row>
<row>
<entry>
<para><literal>retdatap</literal></para></entry>
<entry>
<para>Pointer to the pointer for a <olink targetptr="bdakg">berval</olink> structure
containing the data returned by the server after performing the extended operation.
When done, you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink> 
function.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gargc"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garga"><title>Description</title>
<para>The <function>ldap_extended_operation_s</function> function sends a
request to the server to perform an LDAP v3 extended operation.</para>
<note><para>The LDAP server must support the extended operation. &cnDirectoryServer; supports
a server plug-in interface that you can use to add support for extended operations.
</para></note>
<para><function>ldap_extended_operation_s</function> is a synchronous function,
which directly returns the results of the operation. If you want to perform
other operations while waiting for the results of this operation, call the
asynchronous function <olink targetptr="bdaru">ldap_extended_operation</olink>.
After processing an LDAP v3 extended operation, an LDAP server can return
an object identifier and data in the results. The <literal>retoidp</literal> and <literal>
retdatap</literal> arguments point to these values.</para></sect3>
<sect3 id="gargv"><title>See Also</title>
<para><olink targetptr="bdaru">ldap_extended_operation</olink>,  <olink targetptr="bdaof">ber_flatten</olink></para></sect3>
</sect2>
<sect2 id="bdarw"><title><function>ldap_first_attribute</function></title>
<para>The <function>ldap_first_attribute</function> function returns the name
of the first attribute in an entry returned by the <olink targetptr="bdary">ldap_first_entry
</olink> , the <olink targetptr="bdauc">ldap_next_entry</olink>, or the  <olink targetptr="bdauu">ldap_result</olink> functions.</para>
<sect3 id="garhe"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
     BerElement **ber );</programlisting>
</sect3>
<sect3 id="gargx"><title>Parameters</title>
<table frame="topbot" id="gargp"><title><function>ldap_first_attribute</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
representing the entry returned by the <olink targetptr="bdary">ldap_first_entry</olink> or <olink targetptr="bdauc">ldap_next_entry</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> allocated to
keep track of its current position. Pass this pointer to subsequent calls
to  <olink targetptr="bdaua">ldap_next_attribute</olink> to step through the
entry's attributes.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the name of the first
attribute in an entry. When you are done using this data, you should free
the memory by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.
</para></listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garfq"><title>Example</title>
<para><olink targetptr="ldap-first-attribute-example">Example 21&ndash;14</olink> 
retrieves each attribute for an entry.</para>
<example id="ldap-first-attribute-example"><title>Using <function>ldap_first_attribute
</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)"
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE,
                    my_filter, NULL, 0, &amp;result ) !=
     LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );

/* Retrieve the attributes the entry */
  for ( a = ldap_first_attribute( ld, e, &amp;ber ); a != NULL;
   a = ldap_next_attribute( ld, e, ber ) ) {
    ...
    /* Code to get and manipulate attribute values */
    ...
    }
    ldap_memfree( a );
  }
  /* Free the BerElement from memory when done */
  if ( ber != NULL ) {
    ldap_ber_free( ber, 0 );
  }
...</programlisting>
</example>
</sect3>
<sect3 id="garfo"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink>,  <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute
</olink>, <olink targetptr="bdakh">BerElement</olink></para></sect3>
</sect2>
<sect2 id="bdarx"><title><function>ldap_first_disptmpl</function></title>
<para>The <function>ldap_first_disptmpl</function> function returns the first
template in a list.</para>
<sect3 id="garhd"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );</programlisting>
</sect3>
<sect3 id="gargh"><title>Parameters</title>
<table frame="topbot" id="garft"><title><function>ldap_first_disptmpl</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garfy"><title>Description</title>
<para><function>ldap_first_disptmpl</function> returns the first template
in the list of templates pointed to by the parameter <literal>tmpllistp</literal>. <literal>
tmpllistp</literal>  is typically obtained by calling <olink targetptr="bdata">ldap_init_templates
</olink> .</para></sect3>
<sect3 id="gargw"><title>See Also</title>
<para><olink targetptr="bdaub">ldap_next_disptmpl</olink>,  <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf
</olink></para></sect3>
</sect2>
<sect2 id="bdary"><title><function>ldap_first_entry</function></title>
<para>The <function>ldap_first_entry</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the first directory entry in a chain of search results.</para>
<sect3 id="garfp"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );</programlisting>
</sect3>
<sect3 id="gargz"><title>Parameters</title>
<table frame="topbot" id="gargj"><title><function>ldap_first_entry</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Chain of search results, which are represented by a pointer to the  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the first  <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_ENTRY
</literal> in the chain of search results.</para></listitem>
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> are in the chain of the
search results or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garhc"><title>Description</title>
<para>The <function>ldap_first_entry</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the first directory entry in a chain of search results. Search result entries
are in messages of the type  <literal>LDAP_RES_SEARCH_ENTRY</literal>. You
can use this function in conjunction with the <olink targetptr="bdauc">ldap_next_entry
</olink> function to iterate through the directory entries in a chain of search
results. These functions skip over any messages in the chain that do not have
the type <literal>LDAP_RES_SEARCH_ENTRY</literal>.</para>
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
returned by this function. Because this is a structure within a chain of search
results, freeing this structure will free part of the chain of search results.
When you are done working with the search results, you can free the chain
itself, rather than individual structures within the chain.</para></sect3>
<sect3 id="garfv"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdauc">ldap_next_entry</olink></para></sect3>
</sect2>
<sect2 id="bdarz"><title><function>ldap_first_message</function></title>
<para>The <function>ldap_first_message</function> function returns a pointer
to the first <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
of search results.</para>
<sect3 id="garfw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );</programlisting>
</sect3>
<sect3 id="garfs"><title>Parameters</title>
<table frame="topbot" id="garfz"><title><function>ldap_first_message</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Chain of search results, represented by a pointer to the  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhf"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the first  <olink targetptr="bdaly">LDAPMessage</olink> structure in the chain of search results.</para>
</listitem>
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
are in the chain or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garha"><title>Description</title>
<para>The <function>ldap_first_message</function> function returns a pointer
to the first <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
of search results. You can use this function in conjunction with the  <olink targetptr="bdaud">ldap_next_message</olink> function to iterate through the
chain of search results. You can also call the <olink targetptr="bdatx">ldap_msgtype
</olink> function to determine if each message contains a matching entry,
a message of the type <literal>LDAP_RES_SEARCH_ENTRY</literal>, or a search
reference, a message of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para>
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
returned by this function. Because this is a structure within a chain of search
results, freeing this structure will free part of the chain of search results.
When you are done working with the search results, you can free the chain
itself, rather than individual structures within the chain.</para></sect3>
<sect3 id="gargb"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdaud">ldap_next_message</olink>, <olink targetptr="bdary">ldap_first_entry
</olink>, <olink targetptr="bdasa">ldap_first_reference</olink></para></sect3>
</sect2>
<sect2 id="bdasa"><title><function>ldap_first_reference</function></title>
<para>The <function>ldap_first_reference</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the first search reference in a chain of search results.</para>
<sect3 id="gargq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );</programlisting>
</sect3>
<sect3 id="garhl"><title>Parameters</title>
<table frame="topbot" id="gargm"><title><function>ldap_first_reference</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Chain of search results, which are represented by a pointer to the  <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhk"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the first  <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_REFERENCE
</literal> in the chain of search results.</para></listitem>
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> are in the chain
of the search results or if the function is unsuccessful, returns a <literal>NULLMSG
</literal>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garfu"><title>Description</title>
<para>The <function>ldap_first_reference</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the first search reference in a chain of search results. Search references
are in messages of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>,
continuation references as specified in LDAPv3 that are stored as referral
entries. Like a referral, each continuation reference itself may contain a
number of URLs assumed to be equivalent, and the client should use one of
those URLs.</para>
<para>You can use this function in conjunction with the <olink targetptr="bdaue">
ldap_next_reference</olink> function to iterate through the search references
in a chain of search results. These functions skip over any messages in the
chain that do not have the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para>
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
returned by this function. Because this is a structure within a chain of search
results, freeing this structure will free part of the chain of search results.
When you are done working with the search results, you can free the chain
itself, rather than individual structures within the chain.</para></sect3>
<sect3 id="gargl"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdaue">ldap_next_reference</olink>, <olink targetptr="bdarz">ldap_first_message
</olink></para></sect3>
</sect2>
<sect2 id="bdasb"><title><function>ldap_first_searchobj</function></title>
<para>The <function>ldap_first_searchobj</function> function returns the first
search preference configuration from a data structure defined in the list <literal>
solist</literal> .</para>
<sect3 id="garhh"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );</programlisting>
</sect3>
<sect3 id="garhb"><title>Parameters</title>
<table frame="topbot" id="gargr"><title><function>ldap_first_searchobj</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><parameter>solist</parameter></para></entry>
<entry>
<para>Pointer to the search preference data structures, typically obtained
by calling <olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gargf"><title>Description</title>
<para><literal>ldap_first_searchobj</literal> provides access to LDAP search
preference configuration data. LDAP search preference configurations are typically
used by LDAP client programs to specify which attributes a user may search
by, the labels for the attributes, and the LDAP filters and scopes associated
with those searches.</para></sect3>
<sect3 id="gargs"><title>See Also</title>
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>,  <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
</sect2>
<sect2 id="bdasc"><title><function>ldap_first_tmplcol</function></title>
<para>The <function>ldap_first_tmplcol</function> function returns a pointer
to the first item within a template.</para>
<sect3 id="garhr"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
    struct ldap_tmplitem *row );</programlisting>
</sect3>
<sect3 id="garjf"><title>Parameters</title>
<table frame="topbot" id="garij"><title><function>ldap_first_tmplcol</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>The name of the template to be retrieved.</para></entry>
</row>
<row>
<entry>
<para><literal>row</literal></para></entry>
<entry>
<para>The row in which the item is to be retrieved from.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garih"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gario"><title>Description</title>
<para><function>ldap_first_tmplcol</function> returns a pointer to the first
item (in the first column) of the row, defined by <literal>row</literal>,
within the template defined by <literal>tmpl</literal>.</para></sect3>
<sect3 id="garji"><title>See Also</title>
<para><olink targetptr="bdasd">ldap_first_tmplrow</olink>,  <olink targetptr="bdaug">ldap_next_tmplcol</olink></para></sect3>
</sect2>
<sect2 id="bdasd"><title><function>ldap_first_tmplrow</function></title>
<para>The <function>ldap_first_tmplrow</function> function returns a pointer
to the first row of items in a template.</para>
<sect3 id="garic"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );</programlisting>
</sect3>
<sect3 id="gariq"><title>Parameters</title>
<table frame="topbot" id="garjb"><title><function>ldap_first_tmplrow</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>The name of the template to be retrieved.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garho"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gariy"><title>See Also</title>
<para><olink targetptr="bdauh">ldap_next_tmplrow</olink>,  <olink targetptr="bdasc">ldap_first_tmplcol</olink></para></sect3>
</sect2>
<sect2 id="bdase"><title><function>ldap_free_friendlymap</function></title>
<para>The <function>ldap_free_friendlymap</function> function frees the  <olink targetptr="bdaki">FriendlyMap</olink> structures allocated by the <olink targetptr="bdasj">ldap_friendly_name</olink>  function when no more calls
to it are to be made.</para>
<sect3 id="garhy"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_free_friendlymap( FriendlyMap *map );</programlisting>
</sect3>
<sect3 id="garjj"><title>Parameters</title>
<table frame="topbot" id="garin"><title><function>ldap_free_friendlymap</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>map</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaki">FriendlyMap</olink> mapping
structure in memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhq"><title>Example</title>
<para><olink targetptr="ldap-free-friendlymap-example">Example 21&ndash;15</olink> 
frees memory allocated by the <olink targetptr="bdasj">ldap_friendly_name</olink> 
function.</para>
<example id="ldap-free-friendlymap-example"><title>Using <function>ldap_free_friendlymap
</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;stdio.h>
...
FriendlyMap map = NULL;
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
char *unfriendly_name = "IS";
char *friendly_name;
...
/* Read the ldapfriendly file into the map in memory */
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &amp;map );
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );

/* Since file is in memory, no need to reference it in subsequent calls */
friendly_name = ldap_friendly_name( NULL, "VI", &amp;map );
printf( "Friendly Name for VI: %s\n", friendly_name );
...
ldap_free_friendlymap( map );
...</programlisting>
</example>
</sect3>
<sect3 id="garie"><title>See Also</title>
<para><olink targetptr="bdasj">ldap_friendly_name</olink>,  <olink targetptr="bdaki">FriendlyMap</olink></para></sect3>
</sect2>
<sect2 id="bdasf"><title><function>ldap_free_searchprefs</function></title>
<para>The <function>ldap_free_searchprefs</function> function disposes of
the data structures allocated by <olink targetptr="bdasy">ldap_init_searchprefs</olink>.
</para>
<sect3 id="garit"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_free_searchprefs( struct ldap_searchobj *solist );</programlisting>
</sect3>
<sect3 id="garhs"><title>Parameters</title>
<table frame="topbot" id="garir"><title><function>ldap_free_searchprefs</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>solist</literal></para></entry>
<entry>
<para>Pointer to the data structures, typically obtained by calling  <olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garja"><title>See Also</title>
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>,  <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
</sect2>
<sect2 id="bdasg"><title><function>ldap_free_sort_keylist</function></title>
<para>The <function>ldap_free_sort_keylist</function> function frees the structures
allocated by the <olink targetptr="bdarf">ldap_create_sort_keylist</olink> function.
</para>
<sect3 id="garhx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);</programlisting>
</sect3>
<sect3 id="garht"><title>Parameters</title>
<table frame="topbot" id="gariv"><title><function>ldap_free_sort_keylist</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sortKeyList</literal></para></entry>
<entry>
<para>Array of <olink targetptr="bdamc">LDAPsortkey</olink> structures that
you want to free from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garim"><title>Description</title>
<para>The <function>ldap_free_sort_keylist</function> function frees the array
of <olink targetptr="bdamc">LDAPsortkey</olink> structures allocated by the
 <olink targetptr="bdarf">ldap_create_sort_keylist</olink> function. When
done sorting results, call this function to free the memory that you have
allocated. This function must be called after the <olink targetptr="bdare">ldap_create_sort_control
</olink> function has completed.</para></sect3>
<sect3 id="garif"><title>See Also</title>
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>,  <olink targetptr="bdare">ldap_create_sort_control</olink></para></sect3>
</sect2>
<sect2 id="bdash"><title><function>ldap_free_templates</function></title>
<para>The <function>ldap_free_templates</function> function disposes of the
templates allocated by <olink targetptr="bdata">ldap_init_templates</olink>.</para>
<sect3 id="garjc"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 void ldap_free_templates( struct ldap_disptmpl *tmpllist );</programlisting>
</sect3>
<sect3 id="garjd"><title>Parameters</title>
<table frame="topbot" id="garjg"><title><function>ldap_free_templates</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhz"><title>Description</title>
<para><function>ldap_free_templates</function> releases the templates allocated
by <olink targetptr="bdata">ldap_init_templates</olink>. Each template defined
in the file is an <literal>ldap_disptmpl</literal> structure.</para></sect3>
</sect2>
<sect2 id="bdasi"><title><function>ldap_free_urldesc</function></title>
<para>The <function>ldap_free_urldesc</function> function frees memory allocated
by the <olink targetptr="bdawk">ldap_url_parse</olink> function.</para>
<sect3 id="garib"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_free_urldesc( LDAPURLDesc *ludp );</programlisting>
</sect3>
<sect3 id="garig"><title>Parameters</title>
<table frame="topbot" id="garis"><title><function>ldap_free_urldesc</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ludp</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdams">LDAPURLDesc</olink> structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gariz"><title>Example</title>
<para><olink targetptr="ldap-free-urldesc-example">Example 21&ndash;16</olink> parses
an LDAP URL and then frees the <olink targetptr="bdams">LDAPURLDesc</olink> structure
from memory after verifying that the LDAP URL is valid.</para>
<example id="ldap-free-urldesc-example"><title>Using <function>ldap_free_urldesc</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
char *my_url =
  "ldap://ldap.example.com:1389/dc=example,dc=com?cn,mail,telephoneNumber?
  sub?(sn=Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &amp;ludpp ) ) != 0 ) {
  switch( res ){
    case LDAP_URL_ERR_NOTLDAP:
      printf( "URL does not begin with \"ldap://\"\n" );
      break;
    case LDAP_URL_ERR_NODN:
      printf( "URL does not contain a distinguished name\n" );
      break;
    case LDAP_URL_ERR_BADSCOPE:
      printf( "URL contains an invalid scope\n" );
      break;
    case LDAP_URL_ERR_MEM:
      printf( "Not enough memory\n" );
      break;
    default:
      printf( "Unknown error\n" );
  }
  return( 1 );
}
printf( "URL is a valid LDAP URL\n" );
ldap_free_urldesc( ludpp );
...</programlisting>
</example>
</sect3>
<sect3 id="garia"><title>See Also</title>
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></sect3>
</sect2>
<sect2 id="bdasj"><title><function>ldap_friendly_name</function></title>
<para>The <function>ldap_friendly_name</function> function maps a set of standard
identifiers to their user-friendly counterparts. For example, you can represent
the list of two-letter state codes (CA, IA) with their corresponding state
names (California, Iowa), or map country ISO codes to the full country names.</para>
<note><para><literal>ldapfriendly</literal>, located in <literal>lib/ldapcsdk/etc
</literal>, is a sample file that maps two letter country codes to their full
names. It can be used in context with  <olink targetptr="bdasj">ldap_friendly_name
</olink>.</para></note>
<sect3 id="garhp"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char * ldap_friendly_name( char *filename, char *uname,
    FriendlyMap *map );</programlisting>
</sect3>
<sect3 id="garid"><title>Parameters</title>
<table frame="topbot" id="garik"><title><function>ldap_friendly_name</function> function
parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>filename</literal></para></entry>
<entry>
<para>Name of the file mapping the standard identifiers to the user-friendly
names.</para></entry>
</row>
<row>
<entry>
<para><literal>uname</literal></para></entry>
<entry>
<para>Standard identifier name for which you want to find the user-friendly
name.</para></entry>
</row>
<row>
<entry>
<para><literal>map</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaki">FriendlyMap</olink> mapping
in memory. Initialize this pointer to <literal>NULL</literal> on the first
call, then use it during subsequent calls so that the mapping file does not
need to be read again.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garje"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the user-friendly name for the specified
identifier.</para></listitem>
<listitem><para>If unsuccessful&mdash;for example, if the file cannot be read,
if the file is in a bad format, or if the map parameter is set to <literal>NULL</literal>&mdash;returns
the original identifier (the value passed as the <literal>uname</literal> parameter).
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garil"><title>Description</title>
<para>This function relies on the existence of a text file mapping standard
identifiers to user-friendly names. The names in the file are tab-delimited.</para>
<example id="garii"><title>Unfriendly to Friendly Name Mapping File</title>
<programlisting>&lt;unfriendly_name>        &lt;friendly_name>
AD        Andorra
AE        United Arab Emirates
AF        Afghanistan
AG        Antigua and Barbuda
AI        Anguilla</programlisting>
</example>
</sect3>
<sect3 id="garix"><title>Example</title>
<para><olink targetptr="ldap-friendly-name-example">Example 21&ndash;18</olink> 
reads in a map of user-friendly names and prints the name corresponding to
the standard identifier <literal>IS</literal>.</para>
<example id="ldap-friendly-name-example"><title>Using <function>ldap_friendly_name
</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;stdio.h>
...
FriendlyMap map = NULL;
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
char *unfriendly_name = "IS";
char *friendly_name;
...
/* Read the ldapfriendly file into the map in memory */
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &amp;map );
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );

/* Since file is in memory, no need to reference it in subsequent calls */
friendly_name = ldap_friendly_name( NULL, "VI", &amp;map );
printf( "Friendly Name for VI: %s\n", friendly_name );
...</programlisting>
</example>
</sect3>
<sect3 id="gariw"><title>See Also</title>
<para><olink targetptr="bdase">ldap_free_friendlymap</olink>,  <olink targetptr="bdaki">FriendlyMap</olink></para></sect3>
</sect2>
<sect2 id="bdask"><title><function>ldap_get_dn</function></title>
<para>The <function>ldap_get_dn</function> routine returns the DN for an entry
in a chain of search results.</para>
<sect3 id="garhu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );</programlisting>
</sect3>
<sect3 id="garhw"><title>Parameters</title>
<table frame="topbot" id="garjh"><title><function>ldap_get_dn</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Pointer to an entry in a chain of search results, as returned by the <olink targetptr="bdary">ldap_first_entry</olink> and <olink targetptr="bdauc">ldap_next_entry
</olink>  functions.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garhv"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the DN for the specified entry.</para>
</listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
the appropriate error code in the LDAP structure. To get the error code, call
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garip"><title>Description</title>
<para>You can get an entry from a chain of search results by calling the  <olink targetptr="bdary">ldap_first_entry</olink> and <olink targetptr="bdauc">ldap_next_entry
</olink> functions.</para></sect3>
<sect3 id="gariu"><title>Example</title>
<para><olink targetptr="ldap-get-dn-example">Example 21&ndash;19</olink> prints
the DN for each entry found in a search.</para>
<example id="ldap-get-dn-example"><title>Using <function>ldap_get_dn</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
char *dn;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
  NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* For each matching entry found, print out the name of the entry.*/
for ( e = ldap_first_entry( ld, result ); e != NULL;
  e = ldap_next_entry( ld, e ) ) {
  if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) {
    printf( "dn: %s\n", dn );
    /* Free the memory used for the DN when done */
    ldap_memfree( dn );
  }
}
/* Free the result from memory when done. */
ldap_msgfree( result );
...</programlisting>
</example>
</sect3>
<sect3 id="garkp"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink>,  <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdasq">ldap_get_lderrno
</olink></para></sect3>
</sect2>
<sect2 id="bdasl"><title><function>ldap_get_entry_controls</function></title>
<para>The <function>ldap_get_entry_controls</function> function gets the LDAP
controls included with a directory entry in a set of search results.</para>
<sect3 id="garkd"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
     LDAPControl ***serverctrlsp );</programlisting>
</sect3>
<sect3 id="garlb"><title>Parameters</title>
<table frame="topbot" id="garkz"><title><function>ldap_get_entry_controls</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
representing an entry in a chain of search results.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrlsp</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
which represent the LDAP v3 server controls returned by the server.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garjz"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garkr"><title>Description</title>
<para>The <function>ldap_get_entry_controls</function> function retrieves
the LDAP v3 controls included in a directory entry in a chain of search results.
The LDAP controls are specified in an array of <olink targetptr="bdala">LDAPControl
</olink> structures with each structure representing one LDAP control. Other
controls are returned with results sent from the server. You can call <olink targetptr="bdaun">ldap_parse_result</olink>  to retrieve those controls.</para>
</sect3>
</sect2>
<sect2 id="bdasm"><title><function>ldap_getfilter_free</function></title>
<para>The <function>ldap_getfilter_free</function> function frees the memory
used by a filter set.</para>
<sect3 id="garjy"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_getfilter_free( LDAPFiltDesc *lfdp );</programlisting>
</sect3>
<sect3 id="garkm"><title>Parameters</title>
<table frame="topbot" id="garjo"><title><function>ldap_getfilter_free</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lfdp</literal></para></entry>
<entry>
<para>Pointer to a <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garku"><title>Description</title>
<para>Once you call <function>ldap_getfilter_free</function>, the  <olink targetptr="bdalf">LDAPFiltDesc</olink> structure is no longer valid and cannot
be used again.</para></sect3>
<sect3 id="garjw"><title>Example</title>
<para><olink targetptr="ldap-getfilter-free-example">Example 21&ndash;20</olink> frees
the <olink targetptr="bdalf">LDAPFiltDesc</olink> structure from memory after
all searches are completed.</para>
<example id="ldap-getfilter-free-example"><title>Using <function>ldap_getfilter_free
</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
...
/* Read the filter configuration file into an LDAPFiltDesc structure */
lfdp = ldap_init_getfilter( filter_file );
...
/* Retrieve filters and perform searches */
...
/* Free the configuration file (the LDAPFiltDesc structure) */
ldap_getfilter_free( lfdp );
...</programlisting>
</example>
</sect3>
<sect3 id="garju"><title>See Also</title>
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>,  <olink targetptr="bdasx">ldap_init_getfilter_buf</olink></para></sect3>
</sect2>
<sect2 id="bdasn"><title><function>ldap_getfirstfilter</function></title>
<para>The <function>ldap_getfirstfilter</function> function retrieves the
first filter that is appropriate for a given value.</para>
<sect3 id="garkb"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
     char *tagpat, char *value );</programlisting>
</sect3>
<sect3 id="garla"><title>Parameters</title>
<table frame="topbot" id="garkw"><title><function>ldap_getfirstfilter</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lfdp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
</entry>
</row>
<row>
<entry>
<para><literal>tagpat</literal></para></entry>
<entry>
<para>Regular expression for a tag in the filter configuration.</para></entry>
</row>
<row>
<entry>
<para><literal>value</literal></para></entry>
<entry>
<para>Value for which to find the first appropriate filter.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garjx"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalg">LDAPFiltInfo
</olink>  structure.</para></listitem>
<listitem><para>If no more filters can be returned, returns a <literal>NULL</literal>.
</para></listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garkc"><title>Example</title>
<para><olink targetptr="ldap-getfirstfilter-example">Example 21&ndash;21</olink> 
is based on the <literal>getfilt</literal> command-line program example provided
with the &DirectorySDKForC;. The program prompts the user to enter search
criteria and, based on the criteria entered, it retrieves filters that match
the criteria.</para>
<example id="ldap-getfirstfilter-example"><title>Using <function>ldap_getfirstfilter
</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
LDAPFiltDesc *ldfp;
LDAPFiltInfo *ldfi;
char buf[ 80 ]; /* Contains the search criteria */
int found;
...
/* Load the filter configuration file into an LDAPFiltDesc structure */
if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) {
  perror( "Cannot open filter configuration file" );
  return( 1 );
}

/* Read a string to search for */
printf( "Enter a string to search for: " );
gets( buf );
if ( strlen( buf ) == 0 ) {
  fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]);
  return( 1 );
}

/* Select a filter to use when searching for the value in buf */
found = 0;
for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf );
      ldfi != NULL;
      ldfi = ldap_getnextfilter( ldfp ) ) {

  /* Use the selected filter to search the directory */
  if ( ldap_search_s( ld, "dc=example,dc=com, ldfi->lfi_scope,
   ldfi->lfi_filter, NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_search_s" );
    return( 1 );
  } else {

    /* Once a filter gets results back, stop iterating through
       the different filters */
    if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) {
      break;
    } else {
      ldap_msgfree( result );
    }
  }
}

if ( found == 0 ) {
  printf( "No matching entries found.\n" );
} else {
  printf( "Found %d %s match%s for \"%s\"\n\n", found,
   ldfi->lfi_desc, found == 1 ? "" : "es", buf );
}

ldap_msgfree( result );
ldap_getfilter_free( ldfp );
...</programlisting>
</example>
</sect3>
<sect3 id="garjv"><title>See Also</title>
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>,  <olink targetptr="bdasx">ldap_init_getfilter_buf</olink>, <olink targetptr="bdasr">ldap_getnextfilter
</olink></para></sect3>
</sect2>
<sect2 id="bdaso"><title><function>ldap_get_lang_values</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
use <olink targetptr="bdast">ldap_get_values</olink>.</para></note>
<para>The <function>ldap_get_lang_values</function> function returns a <literal>NULL
</literal> terminated array of an attribute&rsquo;s string values that match
a specified language subtype.</para>
<sect3 id="garkh"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
    const char *target, char **type );</programlisting>
</sect3>
<sect3 id="garjr"><title>Parameters</title>
<table frame="topbot" id="garjs"><title><function>ldap_get_lang_values</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Entry retrieved from the directory.</para></entry>
</row>
<row>
<entry>
<para><literal>target</literal></para></entry>
<entry>
<para>Attribute type (including an optional language subtype) that you want
to retrieve the values of.</para></entry>
</row>
<row>
<entry>
<para><literal>type</literal></para></entry>
<entry>
<para>Pointer to a buffer that returns the attribute type retrieved by this
function.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garkk"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array of the attribute&rsquo;s values.</para></listitem>
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
returns a <literal>NULL</literal> and sets the appropriate error code in the
 <olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garjl"><title>Description</title>
<para>Unlike the <olink targetptr="bdast">ldap_get_values</olink> function,
if a language subtype is specified, this function first attempts to find and
return values that match that subtype&mdash;for example, <literal>cn;lang-en</literal>.
If you want to retrieve binary data from an attribute, call the <olink targetptr="bdasp">ldap_get_lang_values_len</olink>  function.</para></sect3>
<sect3 id="garkv"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink>,  <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdasp">ldap_get_lang_values_len
</olink> , <olink targetptr="bdast">ldap_get_values</olink>,  <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute
</olink></para></sect3>
</sect2>
<sect2 id="bdasp"><title><function>ldap_get_lang_values_len</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
use <olink targetptr="bdasu">ldap_get_values_len</olink>.</para></note>
<para>The <function>ldap_get_lang_values_len</function> function returns a
 <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdakg">
berval</olink> structures, each containing the length and pointer to a binary
value of an attribute for a given entry.</para>
<sect3 id="garks"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
struct berval ** ldap_get_lang_values_len( LDAP *ld,
     LDAPMessage *entry, const char *target, char **type );</programlisting>
</sect3>
<sect3 id="garkl"><title>Parameters</title>
<table frame="topbot" id="garjq"><title><function>ldap_get_lang_values_len</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>target</literal></para></entry>
<entry>
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>type</literal></para></entry>
<entry>
<para>Pointer to a buffer that returns the attribute type retrieved by this
function.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garjm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array of pointers to <olink targetptr="bdakg">berval</olink> structures, which,
in turn, contain pointers to the attribute&rsquo;s binary values.</para>
</listitem>
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
returns a <literal>NULL</literal> and sets the appropriate error code in the
 <olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garjk"><title>Description</title>
<para>Use the <olink targetptr="bdaso">ldap_get_lang_values</olink> routine
if the attribute values are string values.</para></sect3>
<sect3 id="garko"><title>See Also</title>
<para><olink targetptr="bdarw">ldap_first_attribute</olink>,  <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdaso">ldap_get_lang_values
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
</sect2>
<sect2 id="bdasq"><title><function>ldap_get_lderrno</function></title>
<para>The <function>ldap_get_lderrno</function> function gets information
about the last error that occurred for an LDAP operation.</para>
<sect3 id="garkn"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_get_lderrno( LDAP *ld, char **m, char **s );</programlisting>
</sect3>
<sect3 id="garkj"><title>Parameters</title>
<table frame="topbot" id="garky"><title><function>ldap_get_lderrno</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>m</literal></para></entry>
<entry>
<para>In the event of an <errorcode>LDAP_NO_SUCH_OBJECT</errorcode> error
return, this parameter contains the portion of the DN that identifies an existing
entry.</para></entry>
</row>
<row>
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>The text of the error message.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garjt"><title>Returns</title>
<para>The LDAP error code for the last operation.</para></sect3>
<sect3 id="garka"><title>Description</title>
<para><function>ldap_get_lderrno</function> gets information about the last
error that occurred for an LDAP operation. You can also call this function
to get error codes for functions that do not return errors, such as <olink targetptr="bdaua">ldap_next_attribute</olink>.</para></sect3>
<sect3 id="garkq"><title>Example</title>
<para><olink targetptr="ldap-get-lderrno-example">Example 21&ndash;22</olink> attempts
to add a new user to the directory. If the entry identified by a DN does not
exist, the server returns the portion of the DN that matches an existing entry;
this is the variable matched.</para>
<example id="ldap-get-lderrno-example"><title>Using <function>ldap_get_lderrno</function></title>
<programlisting>#include &lt;ldap.h>
LDAP *ld;
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
LDAPMod **list_of_attrs;
char *matched;
int rc;
...
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
  rc = ldap_get_lderrno( ld, &amp;matched, NULL );
  return( rc );
}
...</programlisting>
</example>
<para>In <olink targetptr="ldap-get-lderrno-example">Example 21&ndash;22</olink>,
if no organizational unit named <literal>People</literal> exists, the matched
variable is set to <literal>dc=example,dc=com</literal> .</para></sect3>
<sect3 id="garke"><title>See Also</title>
<para><olink targetptr="bdarq">ldap_err2string</olink>,  <olink targetptr="bdaur">
ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink></para></sect3>
</sect2>
<sect2 id="bdasr"><title><function>ldap_getnextfilter</function></title>
<para>The <function>ldap_getnextfilter</function> function retrieves the next
filter that is appropriate for a given value.</para>
<sect3 id="garkx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );</programlisting>
</sect3>
<sect3 id="garjp"><title>Parameters</title>
<table frame="topbot" id="garki"><title><function>ldap_getnextfilter</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lfdp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garjn"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalg">LDAPFiltInfo
</olink>  structure.</para></listitem>
<listitem><para>If no more filters can be returned, returns a <literal>NULL</literal>.
</para></listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garkg"><title>Description</title>
<para>Call this function to get subsequent filters after calling  <olink targetptr="bdasn">ldap_getfirstfilter</olink>.</para></sect3>
<sect3 id="garkt"><title>Example</title>
<para>See <olink targetptr="ldap-getfirstfilter-example">Example 21&ndash;21</olink>.
</para></sect3>
<sect3 id="garmi"><title>See Also</title>
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink></para></sect3>
</sect2>
<sect2 id="bdass"><title><function>ldap_get_option</function></title>
<para>The function <function>ldap_get_option</function> retrieves session
preferences from an <olink targetptr="bdakj">LDAP</olink> structure.</para>
<sect3 id="garle"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_get_option( LDAP *ld, int option, void *optdata );</programlisting>
</sect3>
<sect3 id="garlx"><title>Parameters</title>
<table frame="topbot" id="garlg"><title><function>ldap_get_option</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>option</literal></para></entry>
<entry>
<para>Option that you want to retrieve. This parameter must be set to one
of the option values.</para></entry>
</row>
<row>
<entry>
<para><literal>optdata</literal></para></entry>
<entry>
<para>Pointer to the buffer in which the value of the option will be put.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para><olink targetptr="ldap-get-options-options">Table 21&ndash;110</olink> describes
the options that you can retrieve with <function>ldap_get_option</function>.</para>
<table frame="topbot" id="ldap-get-options-options"><title>Options for the <function>
ldap_get_options</function> Function</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Option</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>LDAP_OPT_API_FEATURE_INFO</literal></para></entry>
<entry>
<para>Retrieves information about the revision of a supported LDAP feature.
This option is READ-ONLY and cannot be set.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIFeatureInfo
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_API_INFO</literal></para></entry>
<entry>
<para>Retrieves information about the API implementation at execution time
(API version, protocol version, the names of supported API extensions with
their vendor name version, etc.). For details on the structure returned, refer
to the <literal>ldap.h</literal> header file. This option is READ-ONLY and
cannot be set.</para>
<para>The data type for the <literal>optdata</literal> parameter is  <literal>(LDAPAPIInfo
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_CLIENT_CONTROLS</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing the LDAP v3 client controls you want sent with every request
by default.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
***)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DESC</literal></para></entry>
<entry>
<para>Socket descriptor underlying the main LDAP connection. The <literal>LBER_SOCKET
</literal>  data type depends on the platform that you are using:</para>
<itemizedlist>
<listitem><para><literal>int</literal> in UNIX.</para></listitem>
<listitem><para><literal>SOCKET</literal> in Windows.</para><para>The data
type for the <literal>optdata</literal>  parameter is <literal>(LBER_SOCKET
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DEREF</literal></para></entry>
<entry>
<para>Determines how aliases work during a search. <literal>optdata</literal> can
be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_DEREF_NEVER</literal> specifies that aliases
are never dereferenced.</para></listitem>
<listitem><para><literal>LDAP_DEREF_SEARCHING</literal> specifies that aliases
are dereferenced when searching under the base object (but not when finding
the base object).</para></listitem>
<listitem><para><literal>LDAP_DEREF_FINDING</literal> specifies that aliases
are dereferenced when finding the base object (but not when searching under
the base object).</para></listitem>
<listitem><para><literal>LDAP_DEREF_ALWAYS</literal> specifies that aliases
are always dereferenced when finding and searching under the base object.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DNS_FN_PTRS</literal></para></entry>
<entry>
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
DNS functions for getting the host entry of the LDAP server.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_dns_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_ERROR_NUMBER</literal></para></entry>
<entry>
<para>Retrieves the result code for the most recent LDAP error that occurred
in this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_ERROR_STRING</literal></para></entry>
<entry>
<para>Retrieves the error message returned with the result code for the most
recent LDAP error that occurred in this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_EXTRA_THREAD_FN_PTRS</literal></para></entry>
<entry>
<para>Lets you specify the locking and semaphore functions that you want called
when getting results from the server. </para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_extra_thread_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_HOST_NAME</literal></para></entry>
<entry>
<para>Sets the host name (or list of hosts) for the primary LDAP server.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_IO_FN_PTRS</literal></para></entry>
<entry>
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
communication stacks.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_io_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_MATCHED_DN</literal></para></entry>
<entry>
<para>Gets the matched DN value returned with the most recent LDAP error that
occurred for this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal></para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_MEMALLOC_FN_PTRS</literal></para></entry>
<entry>
<para>Gets a pointer to the callback structure which you previously set.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_memalloc_fnsldap_io_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_PROTOCOL_VERSION</literal></para></entry>
<entry>
<para>Version of the protocol supported by your client. You can specify either <literal>
LDAP_VERSION2</literal> or <literal>LDAP_VERSION3.</literal> If no version
is set, the default is <literal>LDAP_VERSION2</literal>. In order to use LDAP
v3 features, you need to set the protocol version to <literal>LDAP_VERSION3</literal>.
</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REBIND_ARG</literal></para></entry>
<entry>
<para>Lets you set the last argument passed to the routine specified by <literal>
LDAP_OPT_REBIND_FN</literal>. You can also set this option by calling the <olink targetptr="bdavh">ldap_set_rebind_proc</olink>  function.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(void
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REBIND_FN</literal></para></entry>
<entry>
<para>Lets you set the routine to be called when you need to authenticate
a connection with another LDAP server (for example, during the course of following
a referral). You can also set this option by calling the <olink targetptr="bdavh">
ldap_set_rebind_proc</olink>  function.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAP_REBINDPROC_CALLBACK
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_RECONNECT</literal></para></entry>
<entry>
<para>If the connection to the server is lost, determines whether or not the
same connection handle should be used to reconnect to the server. By default,
this option is off. You handle failover with the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the same connection
handle can be used to reconnect to the server.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that you want to
create a new connection handle to connect to the server.</para><para>The data
type for the  <literal>optdata</literal> parameter is <literal>(int *)</literal>.
</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REFERRALS</literal></para></entry>
<entry>
<para>Determines whether or not the client should follow referrals. By default,
the client follows referrals. <literal>optdata</literal> can be one of the
following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the server should
follow referrals.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that the server
should not follow referrals.</para><para>The data type for the <literal>optdata</literal> parameter
is <literal>(int *)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REFERRAL_HOP_LIMIT</literal></para></entry>
<entry>
<para>Maximum number of referrals the client should follow in a sequence.
In other words, the client can only be referred this number of times before
it gives up. By default, the maximum number of referrals that the client can
follow in a sequence is 5 for the initial connection. This limit does not
apply to individual requests that generate multiple referrals in parallel.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_RESTART</literal></para></entry>
<entry>
<para>Determines whether or not LDAP I/O operations should be restarted automatically
if they are prematurely aborted. <literal>optdata</literal> can be one of
the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that I/O operations
should be restarted automatically.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that I/O operations
should not be restarted automatically.</para><para>The data type for the <literal>
optdata</literal>  parameter is <literal>(int *)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SERVER_CONTROLS</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing the LDAP v3 server controls you want sent with every request
by default. Typically, since controls are specific to the type of request,
you may want to pass the controls using operation-specific functions, such
as  <olink targetptr="bdaqa">ldap_add_ext</olink>, instead.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
***)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SIZELIMIT</literal></para></entry>
<entry>
<para>Maximum number of entries that should be returned by the server in search
results. The LDAP server may impose a smaller size limit than the limit you
specify as the server administrator also has the ability to set this limit.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SSL</literal></para></entry>
<entry>
<para>Determines whether or not SSL is enabled. <literal>optdata</literal> can
be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that SSL is enabled.</para>
</listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that SSL is disabled.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_THREAD_FN_PTRS</literal></para></entry>
<entry>
<para>Lets you specify the thread function pointers. </para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_thread_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_TIMELIMIT</literal></para></entry>
<entry>
<para>Maximum number of seconds that should be spent by the server when answering
a search request. The LDAP server may impose a shorter time limit than the
limit you specify as the server administrator also has the ability to set
this limit.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_EXTIO_FN_PTRS</literal></para></entry>
<entry>
<para>Extended I/O function callback option.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_CONNECT_TIMEOUT</literal></para></entry>
<entry>
<para>Value of a time out (expressed in milliseconds) for non-blocking connect
call.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_SOCKBUF</literal></para></entry>
<entry>
<para>Socket buffer structure associated to the LDAP connection.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>See also <citerefentry><refentrytitle>ldap_get_option</refentrytitle>
<manvolnum>3LDAP</manvolnum></citerefentry> for details on <literal>LDAP_OPT_X_SASL*
</literal> parameters.</para></sect3>
<sect3 id="garmm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garli"><title>Examples</title>
<para><olink targetptr="ldap-get-options-example">Example 21&ndash;23</olink> gets
the session preference for the maximum number of entries to be returned from
search operations.</para>
<example id="ldap-get-options-example"><title>Using <function>ldap_get_option</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
int max_ret;
...
/* Get the maximum number of entries returned */
if (ldap_get_option, LDAP_OPT_SIZELIMIT, &amp;max_ret) != LDAP_SUCCESS) {
  ldap_perror( ld, "ldap_get_option" );
  return( 1 );
}</programlisting>
</example>
<para><olink targetptr="ldap-get-options-example">Example 21&ndash;23</olink> could
also include the following two small sections of code that show how to use
the <literal>LDAP_OPT_API_FEATURE_INFO</literal> and the <literal>LDAP_OPT_API_INFO
</literal> options, respectively.</para>
<example id="garlu"><title>Using <structname>LDAP_OPT_API_FEATURE_INFO</structname> and <structname>
LDAP_OPT_API_INFO</structname></title>
<programlisting>LDAPIIFeatureInfo ldfi;
ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION;
ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW";
if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &amp;ldfi)==0) {
/* use the info here */ }

LDAPIInfo ldai;
ldai.ldapiai_info_version = LDAP_API_INFO_VERSION;
if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &amp;ldia ) == 0) {
/* use the ldai info here */
}</programlisting>
</example>
</sect3>
<sect3 id="garmf"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavg">ldap_set_option</olink></para></sect3>
</sect2>
<sect2 id="bdast"><title><function>ldap_get_values</function></title>
<para>The <function>ldap_get_values</function> function returns a <literal>NULL</literal> terminated
array of an attribute&rsquo;s string values for a given entry.</para>
<sect3 id="garmv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
     const char *target );</programlisting>
</sect3>
<sect3 id="garlt"><title>Parameters</title>
<table frame="topbot" id="garmt"><title><function>ldap_get_values</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>target</literal></para></entry>
<entry>
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garms"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array of the attribute&rsquo;s values.</para></listitem>
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
returns a <literal>NULL</literal> and sets the appropriate error code in the
 <olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garmk"><title>Description</title>
<para>Use the <olink targetptr="bdasu">ldap_get_values_len</olink> function
if the attribute values are binary.</para></sect3>
<sect3 id="garmq"><title>Example</title>
<para><olink targetptr="ldap-get-values-example">Example 21&ndash;25</olink> gets
and prints the values of an attribute in an entry. This example assumes that
all attributes have string values.</para>
<example id="ldap-get-values-example"><title>Using <function>ldap_get_values</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a;
char **vals;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
int i;
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
  NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );

/* Get the first matching attribute */
a = ldap_first_attribute( ld, e, &amp;ber );

/* Get the values of the attribute */
if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
  for ( i = 0; vals[i] != NULL; i++ ) {
    /* Print the name of the attribute and each value */
    printf( "%s: %s\n", a, vals[i] );
  }
  /* Free the attribute values from memory when done. */
  ldap_value_free( vals );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garlm"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink>,  <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdasu">ldap_get_values_len
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
</sect2>
<sect2 id="bdasu"><title><function>ldap_get_values_len</function></title>
<para>The <function>ldap_get_values_len</function> function returns a <literal>NULL
</literal>  terminated array of pointers to <olink targetptr="bdakg">berval</olink> structures,
each containing the length and pointer to a binary value of an attribute for
a given entry.</para>
<sect3 id="garmg"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 struct berval ** ldap_get_values_len( LDAP *ld,
    LDAPMessage *entry, const char *target );</programlisting>
</sect3>
<sect3 id="garlo"><title>Parameters</title>
<table frame="topbot" id="garlj"><title><function>ldap_get_values_len</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>target</literal></para></entry>
<entry>
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garmd"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
array of pointers to <structname>berval</structname> structures, which in
turn contains pointers to the attribute&rsquo;s binary values.</para></listitem>
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
returns  <literal>NULL</literal> and sets the appropriate error code in the
 <olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garld"><title>Description</title>
<para>Use the <olink targetptr="bdast">ldap_get_values</olink> routine if
the attribute values are string values.</para></sect3>
<sect3 id="garlz"><title>Example</title>
<para><olink targetptr="ldap-get-values-len-example">Example 21&ndash;26</olink> 
gets the first value of the <literal>jpegPhoto</literal> attribute and saves
the JPEG data to a file.</para>
<example id="ldap-get-values-len-example"><title><function>ldap_get_values_len</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
struct berval photo_data;
struct berval **list_of_photos;
FILE *out;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL,
  0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Get the first matching entry.*/
e = ldap_first_entry( ld, result );

/* Get the value of the jpegPhoto attribute */
if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) !=
     NULL ) {
  /* Prepare to write the JPEG data to a file */
  if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) {
    perror( "fopen" );
    return( 1 );
  }
  /* Get the first JPEG */
  photo_data = *list_of_photos[0];
  /* Write the JPEG data to a file */
  fwrite( photo_data.bv_val, photo_data.bv_len, 1, out );
  fclose( out );
  /* Free the attribute values from memory when done. */
  ldap_value_free_len( list_of_photos );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garll"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink>,  <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdast">ldap_get_values
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
</sect2>
<sect2 id="bdasv"><title><function>ldap_init</function></title>
<para>The <function>ldap_init</function> function initializes a session with
an LDAP server and returns an <olink targetptr="bdakj">LDAP</olink> structure
that represents the context of the connection to that server.</para>
<sect3 id="garlk"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP * ldap_init( const char *defhost, int defport );</programlisting>
</sect3>
<sect3 id="garmh"><title>Parameters</title>
<table frame="topbot" id="garmo"><title><function>ldap_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>defhost</literal></para></entry>
<entry>
<para>Space-delimited list of one or more host names (or IP address in dotted
notation, such as "141.211.83.36") of the LDAP servers that you want the LDAP
client to connect to. The names can be in <replaceable>hostname</replaceable>:<replaceable>
portnumber</replaceable>  format (in which case, <replaceable>portnumber</replaceable> overrides
the port number specified by the <literal>defport</literal> argument.</para>
</entry>
</row>
<row>
<entry>
<para><literal>defport</literal></para></entry>
<entry>
<para>Default port number of the LDAP server. To specify the standard LDAP
port (port 389), use <literal>LDAP_PORT</literal> as the value for this parameter.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garmj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdakj">LDAP
</olink>  structure.</para></listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garlf"><title>Description</title>
<para>The <function>ldap_init</function> function initializes a session with
an LDAP server by allocating an <olink targetptr="bdakj">LDAP</olink> structure
containing information about the session including the host name and port
of the LDAP server, preferences for the session (such as the maximum number
of entries to return in a search), and the error code of the last LDAP operation
performed. The  <olink targetptr="bdakj">LDAP</olink> structure defaults to
LDAP v2. It is highly recommended to set it to LDAP v3 using the <olink targetptr="bdavg">ldap_set_option</olink>.</para>
<note><para><olink targetptr="bdasv">ldap_init</olink> does not open a connection
to the LDAP server. The actual connection opening will occur when the first
operation is attempted. Certain fields in the <olink targetptr="bdakj">LDAP</olink> structure
can be set using <olink targetptr="bdavg">ldap_set_option</olink>.</para></note>
<para>You can specify a list of LDAP servers to which you want to attempt
to connect by passing a space-delimited list of the host names as the <literal>defhost
</literal> argument. Your client will attempt to connect to the first LDAP
server in the list. If the attempt fails, your client will attempt to connect
to the next LDAP server in the list. In <olink targetptr="ldap-init-example">Example
21&ndash;27</olink> <literal>ld1.example.com</literal>, port  <literal>389</literal>.
If that server does not respond, the client will attempt to connect to the
LDAP server on <literal>ld2.example.com</literal>, port <literal>389</literal>.
If that server does not respond, the client will use the server on <literal>ld3.example.com
</literal> , port <literal>389</literal>.</para>
<example id="ldap-init-example"><title>Space-Delimited List for <function>ldap_init
</function></title>
<programlisting>...
LDAP *ld
...
ld = ldap_init( "ld1.example.com ld2.example.com ld3.example.com",
                LDAP_PORT );</programlisting>
</example>
<para>If any of the servers do not use the default port specified by the  <literal>
defport</literal> argument, use the <replaceable>hostname</replaceable>: <replaceable>
portnumber</replaceable> format to specify the server name. In  <olink targetptr="ldap-init-example">Example 21&ndash;27</olink> <literal>ld1.example.com
</literal>, port <literal>389</literal>. If that server does not respond,
the client will attempt to connect to the LDAP server on <literal>ld2.example.com
</literal>, port <literal>1389</literal>.</para>
<example id="ldap-init-example2"><title><function>ldap_init</function> Example
Using Variable Argument</title>
<programlisting>...
LDAP *ld
...
ld = ldap_init( "ld1.example.com ld2.example.com:1389", LDAP_PORT );</programlisting>
</example>
<note><para>If you are connecting to a secure LDAP server over SSL, you should
be calling the <olink targetptr="bdavs">ldapssl_init</olink> function.</para>
</note>
</sect3>
<sect3 id="garmr"><title>Example</title>
<para><olink targetptr="ldap-init-example3">Example 21&ndash;29</olink>  initializes
a session with the LDAP server at <literal>ldap.example.com:389</literal>,
and sets a session preference that identifies the client as an LDAP v3 client.</para>
<example id="ldap-init-example3"><title>Using <function>ldap_init</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;

/* Specify the host name of the LDAP server. */
char *ldap_host = "ldap.example.com";

/* Because the LDAP server is running on the standard LDAP port (port 389),
 * you can use LDAP_PORT to identify the port number. */
int ldap_port = LDAP_PORT;
...
/* Initialize the session with ldap.example.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}

/* Specify the LDAP version supported by the client. */
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &amp;version );

...
/* Subsequent calls that authenticate to the LDAP server. */
...</programlisting>
</example>
</sect3>
<sect3 id="garly"><title>See Also</title>
<para><olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink> , <olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdavj">ldap_simple_bind_s
</olink></para></sect3>
</sect2>
<sect2 id="bdasw"><title><function>ldap_init_getfilter</function></title>
<para>The <function>ldap_init_getfilter</function> function reads a valid
LDAP filter configuration file (such as <literal>ldapfilter.conf</literal>)
and returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.
</para>
<note><para><literal>ldapfilter.conf</literal>, the sample LDAP filter configuration
file located in <literal>lib/ldapcsdk/etc</literal>  directory, can be used
in context with <olink targetptr="bdasw">ldap_init_getfilter</olink> .</para>
</note>
<sect3 id="garmu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAPFiltDesc * ldap_init_getfilter( char *fname );</programlisting>
</sect3>
<sect3 id="garln"><title>Parameters</title>
<table frame="topbot" id="garlp"><title><function>ldap_init_getfilter</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>fname</literal></para></entry>
<entry>
<para>Name of the LDAP filter configuration file to use.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garlq"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc
</olink>  structure.</para></listitem>
<listitem><para>If unsuccessful (for example, if there is an error reading
the file), returns a <literal>NULL</literal>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garls"><title>Example</title>
<para><olink targetptr="load-config-example">Example 21&ndash;30</olink> 
loads a filter configuration file named <literal>myfilters.conf</literal> into
memory.</para>
<example id="load-config-example"><title>Loading a Filter Configuration File</title>
<programlisting>#include &lt;ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
...
lfdp = ldap_init_getfilter( filter_file );
...</programlisting>
</example>
</sect3>
<sect3 id="garmn"><title>See Also</title>
<para><olink targetptr="bdasx">ldap_init_getfilter_buf</olink>,  <olink targetptr="bdasm">ldap_getfilter_free</olink></para></sect3>
</sect2>
<sect2 id="bdasx"><title><function>ldap_init_getfilter_buf</function></title>
<para>The <function>ldap_init_getfilter_buf</function> function reads LDAP
filter configuration information from a buffer and returns a pointer to an
 <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
<sect3 id="garma"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );</programlisting>
</sect3>
<sect3 id="garml"><title>Parameters</title>
<table frame="topbot" id="garlh"><title><function>ldap_init_getfilter_buf</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>Buffer containing LDAP filter configuration information.</para></entry>
</row>
<row>
<entry>
<para><literal>buflen</literal></para></entry>
<entry>
<para>Size of the buffer</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garmp"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc
</olink>  structure.</para></listitem>
<listitem><para>If unsuccessful&mdash;for example, if there is an error reading
the file&mdash;returns a <literal>NULL</literal>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garlc"><title>Example</title>
<para><olink targetptr="ldap-init-getfilter-example">Example 21&ndash;31</olink> 
copies the following filter configuration to a buffer in memory and uses this
buffer to fill an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
<programlisting>"ldap-example"
  "@"      " "    "(mail=%v)"            "email address"
            "(mail=%v*)"            "start of email address"</programlisting>
<example id="ldap-init-getfilter-example"><title>Using <function>ldap_init_getfilter
</function></title>
<programlisting>#include &lt;string.h>
#include &lt;ldap.h>
...
LDAPFiltDesc *lfdp;
char filtbuf[ 1024 ];
...
/* Create the filter config buffer */
strcpy( filtbuf, "\"ldap-example\"\n" );
strcat( filtbuf, " \"@\"\t\" \"\t\"(mail=%v)\"\t\"email address\"\n" );
strcat( filtbuf, " \t\t\"(mail=%v*)\"\t\"start of email address\"\n" );
lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );
...</programlisting>
</example>
</sect3>
<sect3 id="garlr"><title>See Also</title>
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>,  <olink targetptr="bdasm">ldap_getfilter_free</olink></para></sect3>
</sect2>
<sect2 id="bdasy"><title><function>ldap_init_searchprefs</function></title>
<para>The <function>ldap_init_searchprefs</function> function reads a sequence
of  search preference configurations from a valid LDAP <literal>searchpref</literal> configuration
file.</para>
<sect3 id="garlv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );</programlisting>
</sect3>
<sect3 id="garmb"><title>Parameters</title>
<table frame="topbot" id="garmc"><title><function>ldap_init_searchprefs</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>file</literal></para></entry>
<entry>
<para>Pointer to a valid LDAP <literal>searchpref</literal> configuration
file.</para></entry>
</row>
<row>
<entry>
<para><literal>solistp</literal></para></entry>
<entry>
<para>Pointer to a list of search preference data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garlw"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SEARCHPREF_ERR_VERSION</literal>.</para>
</listitem>
<listitem><para><literal>LDAP_SEARCHPREF_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para>Upon success, <literal>0</literal> is returned and <literal>solistp
</literal>  is set to point to a list of search preference data structures.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garme"><title>Description</title>
<para><function>ldap_init_searchprefs</function> provides a standard way to
access LDAP search preference configuration data.</para>
<note><para>LDAP search preference configurations are typically used by LDAP
client programs to specify which attributes a user may search by, labels for
the attributes, and LDAP filters and scopes associated with those searches.
Client software presents these choices to a user, who can then specify the
type of search to be performed.</para></note>
</sect3>
<sect3 id="garog"><title>See Also</title>
<para><olink targetptr="bdasf">ldap_free_searchprefs</olink>,  <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
</sect2>
<sect2 id="bdasz"><title><function>ldap_init_searchprefs_buf</function></title>
<para>The <function>ldap_init_searchprefs_buf</function> function reads a
sequence of search preference  configurations from the parameter, <literal>buf</literal>.
</para>
<sect3 id="garnx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_init_searchprefs_buf( char *buf, long buflen,
    struct ldap_searchobj **solistp );</programlisting>
</sect3>
<sect3 id="garoa"><title>Parameters</title>
<table frame="topbot" id="garnr"><title><function>ldap_init_searchprefs_buf</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>Pointer to data in the format defined for an LDAP search preference
configuration file.</para></entry>
</row>
<row>
<entry>
<para><literal>buflen</literal></para></entry>
<entry>
<para>The size of <literal>buf</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>solistp</literal></para></entry>
<entry>
<para>Pointer to a list of search preference data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garok"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SEARCHPREF_ERR_VERSION</literal> if <literal>buf</literal> points
to data that is newer than can be handled.</para></listitem>
<listitem><para><literal>LDAP_SEARCHPREF_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para>Upon success, <literal>0</literal> is returned and <literal>solistp
</literal>  is set to point to a list of search preference data structures.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garnq"><title>Description</title>
<para><function>ldap_init_searchprefs_buf</function> reads a sequence of search
preference  configurations from <literal>buf</literal>.</para>
<note><para>LDAP search preference configurations are typically used by LDAP
client programs to specify which attributes a user may search by, labels for
the attributes, and LDAP filters and scopes associated with those searches.
Client software presents these choices to a user, who can then specify the
type of search to be performed.</para></note>
</sect3>
<sect3 id="garna"><title>See Also</title>
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>,  <olink targetptr="bdasf">ldap_free_searchprefs</olink></para></sect3>
</sect2>
<sect2 id="bdata"><title><function>ldap_init_templates</function></title>
<para>The <function>ldap_init_templates</function> function reads a sequence
of templates from a valid LDAP template configuration file.</para>
<sect3 id="garny"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );</programlisting>
</sect3>
<sect3 id="garng"><title>Parameters</title>
<table frame="topbot" id="garoi"><title><function>ldap_init_templates</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>file</literal></para></entry>
<entry>
<para>Pointer to a valid LDAP template configuration file.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garoh"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
</literal>  is configured.</para></listitem>
<listitem><para>Upon error:</para>
<itemizedlist>
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
to data that is newer than can be handled.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
with the format of the templates buffer or file.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
read.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garnp"><title>Description</title>
<para><function>ldap_init_templates</function> reads a sequence of templates
from a valid LDAP template configuration file. Each template defined in the
file is an  <literal>ldap_disptmpl</literal> structure.</para></sect3>
<sect3 id="garob"><title>See Also</title>
<para><olink targetptr="bdatb">ldap_init_templates_buf</olink>,  <olink targetptr="bdash">ldap_free_templates</olink></para></sect3>
</sect2>
<sect2 id="bdatb"><title><function>ldap_init_templates_buf</function></title>
<para>The <function>ldap_init_templates_buf</function> function reads a sequence
of templates from a buffer.</para>
<sect3 id="garnb"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
int ldap_init_templates_buf( char *buf, long buflen,
    struct ldap_disptmpl **tmpllistp );</programlisting>
</sect3>
<sect3 id="garnw"><title>Parameters</title>
<table frame="topbot" id="garoq"><title><function>ldap_init_templates_buf</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>buf</literal></para></entry>
<entry>
<para>Pointer to data in the format defined for a valid LDAP template configuration
file.</para></entry>
</row>
<row>
<entry>
<para><literal>buflen</literal></para></entry>
<entry>
<para>The size of <literal>buf</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garnm"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
</literal>  is configured.</para></listitem>
<listitem><para>Upon error:</para>
<itemizedlist>
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
to data that is newer than can be handled.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
with the format of the templates buffer or file.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
read.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garnt"><title>Description</title>
<para>The <function>ldap_init_templates_buf</function> function reads a sequence
of templates from a buffer.</para></sect3>
<sect3 id="garor"><title>See Also</title>
<para><olink targetptr="bdata">ldap_init_templates</olink>,  <olink targetptr="bdash">ldap_free_templates</olink></para></sect3>
</sect2>
<sect2 id="bdatc"><title><function>ldap_is_dns_dn</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>The <function>ldap_is_dns_dn</function> function determines whether
a DN string is of the experimental DNS-style DN (generally in the form of
an RFC 822 email address) or the RFC 1779 formatted DN.</para>
<sect3 id="garnl"><title>Description</title>
<para>This function is specific to LDAP v2 and should not be used when dealing
with LDAP v3 servers or data.</para>
<note><para>More information can be found in <citetitle>RFC 1779 - A String
Representation of Distinguished Names</citetitle> (<ulink
url="http://www.faqs.org/rfcs/rfc1779.html" type="text_url"></ulink>) and <citetitle>
RFC 822 - Standard for the Format of ARPA Internet Text Messages</citetitle> (<ulink
url="http://www.faqs.org/rfcs/rfc822.html" type="text_url"></ulink>).</para>
</note>
</sect3>
</sect2>
<sect2 id="bdatd"><title><function>ldap_is_ldap_url</function></title>
<para>The <function>ldap_is_ldap_url</function> function determines whether
or not a URL is an LDAP URL.</para>
<sect3 id="garnd"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_is_ldap_url( const char *url );</programlisting>
</sect3>
<sect3 id="garol"><title>Parameters</title>
<table frame="topbot" id="garmy"><title><function>ldap_is_ldap_url</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>The URL that you want to check.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garop"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>1</literal> if the URL is an LDAP URL.</para>
</listitem>
<listitem><para><literal>0</literal> if the URL is not an LDAP URL.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garmw"><title>Description</title>
<para>The <function>ldap_is_ldap_url</function> function determines whether
or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to <literal>
ldap://</literal>  (or <literal>ldaps://</literal>, if the server is communicating
over a SSL connection).</para></sect3>
<sect3 id="garnc"><title>Example</title>
<para><olink targetptr="ldap-is-ldap-url-example">Example 21&ndash;32</olink> determines
if a URL is a LDAP URL.</para>
<example id="ldap-is-ldap-url-example"><title>Using <function>ldap_is_ldap_url</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
char *my_url = "ldap://ldap.sun.com/dc=example,dc=com";
...
if ( ldap_is_ldap_url( my_url ) != 0 ) {
  printf( "%s is an LDAP URL.\n", my_url );
} else {
  printf( "%s is not an LDAP URL.\n", my_url );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garnj"><title>See Also</title>
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></sect3>
</sect2>
<sect2 id="bdate"><title><function>ldap_keysort_entries</function></title>
<para>The <function>ldap_keysort_entries</function> function is used for sorting
entries.</para>
<sect3 id="garod"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
 int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
    void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
    LDAP_KEYFREE_CALLBACK *fre );</programlisting>
</sect3>
<sect3 id="garoe"><title>Parameters</title>
<table frame="topbot" id="garns"><title><function>ldap_keysort_entries</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>chain</literal></para></entry>
<entry>
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>arg</literal></para></entry>
<entry>
<para>Pointer to an additional argument that you want to pass.</para></entry>
</row>
<row>
<entry>
<para><literal>gen</literal></para></entry>
<entry>
<para>Callback used to generate the key(s) for sorting once the compare function
has been applied.</para></entry>
</row>
<row>
<entry>
<para><literal>cmp</literal></para></entry>
<entry>
<para>Comparison function used when sorting the values.</para></entry>
</row>
<row>
<entry>
<para><literal>fre</literal></para></entry>
<entry>
<para>Callback used to free the key once the compare function has been applied.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garnk"><title>See Also</title>
<para><olink targetptr="bdalu">LDAP_KEYGEN_CALLBACK</olink>,  <olink targetptr="bdals">LDAP_KEYCMP_CALLBACK</olink>, <olink targetptr="bdalt">LDAP_KEYFREE_CALLBACK
</olink></para></sect3>
</sect2>
<sect2 id="bdatf"><title><function>ldap_memcache_destroy</function></title>
<para>The <function>ldap_memcache_destroy</function> function frees an  <olink targetptr="bdalx">LDAPMemCache</olink> structure from memory.</para>
<sect3 id="garnv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_memcache_destroy( LDAPMemCache *cache );</programlisting>
</sect3>
<sect3 id="garon"><title>Parameters</title>
<table frame="topbot" id="garmx"><title><function>ldap_memcache_destroy</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>cache</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
that you want freed from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garoc"><title>Description</title>
<para>The <function>ldap_memcache_destroy</function> function frees the specified <olink targetptr="bdalx">LDAPMemCache</olink> structure from memory. Call this function
after you are done working with a cache.</para></sect3>
<sect3 id="garoj"><title>See Also</title>
<para><olink targetptr="bdati">ldap_memcache_init</olink></para></sect3>
</sect2>
<sect2 id="bdatg"><title><function>ldap_memcache_flush</function></title>
<para>The <function>ldap_memcache_flush</function> function flushes items
from the specified cache.</para>
<sect3 id="garne"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
     int scope );</programlisting>
</sect3>
<sect3 id="garoo"><title>Parameters</title>
<table frame="topbot" id="garnu"><title><function>ldap_memcache_flush</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>cache</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
that you want to flush entries from.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>Base DN identifying the search requests that you want flushed from the
cache. If the base DN of a search request is within the scope specified by
this DN and the scope argument, the search request is flushed from the cache.
If this argument is NULL, the entire cache is flushed.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope that (together with the <literal>dn</literal> argument) identifies
the search requests that you want flushed from the cache. If the base DN of
the request is within the scope specified by this argument and the <literal>dn</literal> argument,
the request is flushed from the cache. This argument can have one of the following
values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal></para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal></para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal></para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garom"><title>Description</title>
<para>The <function>ldap_memcache_flush</function> function flushes search
requests from the cache. If the base DN of a search request is within the
scope specified by the <literal>dn</literal> and scope arguments, the search
request is flushed from the cache. If no DN is specified, the entire cache
is flushed.</para></sect3>
</sect2>
<sect2 id="bdath"><title><function>ldap_memcache_get</function></title>
<para>The <function>ldap_memcache_get</function> function gets the in-memory
cache associated with an LDAP connection handle.</para>
<sect3 id="garnf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );</programlisting>
</sect3>
<sect3 id="garof"><title>Parameters</title>
<table frame="topbot" id="garnn"><title><function>ldap_memcache_get</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>cachep</literal></para></entry>
<entry>
<para>When you call <function>ldap_memcache_get</function>, it sets this parameter
to the pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
associated with the connection handle.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garno"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
connection handle was retrieved successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garni"><title>Description</title>
<para>The <function>ldap_memcache_get</function> function gets the cache associated
with the specified connection handle (<olink targetptr="bdakj">LDAP</olink> structure).
This cache is used by all search requests made through that connection. You
can call this function if you want to associate a cache with multiple LDAP
connection handles. For example, you can call this function to get the cache
associated with one connection, then you can call the <olink targetptr="bdatj">ldap_memcache_set
</olink> function to associate the cache with another connection.</para></sect3>
<sect3 id="garmz"><title>See Also</title>
<para><olink targetptr="bdatj">ldap_memcache_set</olink></para></sect3>
</sect2>
<sect2 id="bdati"><title><function>ldap_memcache_init</function></title>
<para>The <function>ldap_memcache_init</function> function creates an in-memory
cache for your LDAP client that you can associate with an LDAP connection.</para>
<sect3 id="garnz"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_memcache_init( unsigned long ttl, unsigned long size,
     char **baseDNs, struct ldap_thread_fns *thread_fns,
     LDAPMemCache **cachep );</programlisting>
</sect3>
<sect3 id="garnh"><title>Parameters</title>
<table frame="topbot" id="garqm"><title><function>ldap_memcache_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ttl</literal></para></entry>
<entry>
<para>The maximum amount of time (in seconds) that an item can be cached.
If  <literal>0</literal>, there is no limit to the amount of time that an
item can be cached.</para></entry>
</row>
<row>
<entry>
<para><literal>size</literal></para></entry>
<entry>
<para>Maximum amount of memory (in bytes) that the cache will consume. If
 <literal>0</literal>, the cache has no size limit.</para></entry>
</row>
<row>
<entry>
<para><literal>baseDNs</literal></para></entry>
<entry>
<para>An array of the base DN strings representing the base DNs of the search
requests you want cached. If not <literal>NULL</literal>, only the search
requests with the specified base DNs will be cached. If <literal>NULL</literal>,
all search requests are cached.</para></entry>
</row>
<row>
<entry>
<para><literal>thread_fns</literal></para></entry>
<entry>
<para>An <olink targetptr="bdamr">ldap_thread_fns</olink> structure specifying
the functions that you want used to ensure that the cache is thread-safe.
You should specify this if you have multiple threads that are using the same
connection handle and cache. If you are not using multiple threads, pass <literal>
NULL</literal> for this parameter.</para></entry>
</row>
<row>
<entry>
<para><literal>cachep</literal></para></entry>
<entry>
<para>When you call this function, it sets this parameter to the pointer to
the newly created <olink targetptr="bdalx">LDAPMemCache</olink> structure.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garqb"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
connection handle was retrieved successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the initial
size of the cache (specified by the size argument) is too small.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garqf"><title>Description</title>
<para>The <function>ldap_memcache_init</function> function creates an in-memory,
client-side cache that you can use to cache search requests. The function
passes back a pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
which represents the cache. You should call the <olink targetptr="bdatj">ldap_memcache_set
</olink> function to associate this cache with an LDAP connection handle (an
 <olink targetptr="bdakj">LDAP</olink> structure).</para>
<para>The cache uses search criteria as the key to cached items. When you
send a search request, the cache checks the search criteria to determine if
that request has been cached previously. If the request was cached, the search
results are read from the cache. To flush the cache, call the <olink targetptr="bdatg">ldap_memcache_flush</olink>  function. When you are done
with the cache, you can free it from memory by calling the <olink targetptr="bdatf">ldap_memcache_destroy</olink> function.</para>
<note><para>On Windows systems, if the <olink targetptr="bdati">ldap_memcache_init
</olink>  function returns an <errorcode>LDAP_PARAM_ERROR</errorcode> result
code, verify that your client is using the version of the <literal>nsldap32v30.dll
</literal> file provided with the &DirectorySDKForC;.</para></note>
</sect3>
<sect3 id="garpz"><title>See Also</title>
<para><olink targetptr="bdalx">LDAPMemCache</olink>, <olink targetptr="bdatj">ldap_memcache_set
</olink> , <olink targetptr="bdatg">ldap_memcache_flush</olink>,  <olink targetptr="bdatf">ldap_memcache_destroy</olink>, <olink targetptr="bdatk">ldap_memcache_update
</olink></para></sect3>
</sect2>
<sect2 id="bdatj"><title><function>ldap_memcache_set</function></title>
<para>The <function>ldap_memcache_set</function> function associates an in-memory
cache with an LDAP connection handle.</para>
<sect3 id="garpr"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );</programlisting>
</sect3>
<sect3 id="garqp"><title>Parameters</title>
<table frame="topbot" id="garpl"><title><function>ldap_memcache_set</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>cache</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
which represents the cache that you want used for this connection.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garpy"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
connection handle was retrieved successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the initial
size of the cache (specified by the size argument) is too small.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garqa"><title>Description</title>
<para>The <function>ldap_memcache_set</function> function associates a cache
(created by calling <olink targetptr="bdati">ldap_memcache_init</olink>) with
an LDAP connection handle. You can call this function if you want to associate
a cache with multiple LDAP connection handles. For example, you can call the <olink targetptr="bdath">ldap_memcache_get</olink>  function to get the cache associated
with one connection, then you can call  <function>ldap_memcache_set</function> to
associate the cache with another connection.</para>
<para>After you call this function, search requests made over the specified
LDAP connection will use this cache. Calling the <olink targetptr="bdawh">ldap_unbind
</olink> function will disassociate the cache from the LDAP connection handle.</para>
</sect3>
<sect3 id="garpa"><title>See Also</title>
<para><olink targetptr="bdati">ldap_memcache_init</olink>,  <olink targetptr="bdath">ldap_memcache_get</olink></para></sect3>
</sect2>
<sect2 id="bdatk"><title><function>ldap_memcache_update</function></title>
<para>The <function>ldap_memcache_update</function> function checks the cache
for items that have expired and removes them.</para>
<sect3 id="garot"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
void ldap_memcache_update( LDAPMemCache *cache );</programlisting>
</sect3>
<sect3 id="garql"><title>Parameters</title>
<table frame="topbot" id="garou"><title><function>ldap_memcache_update</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>cache</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
which represents the cache that you want to updated.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garox"><title>Description</title>
<para>The <function>ldap_memcache_update</function> function checks the cache
for items that have expired and removes them. This check is typically done
as part of the way the cache normally works. You do not need to call this
function unless you want to update the cache at this point in time.</para>
<tip><para>This function is only useful in a multithreaded application, since
it will not return until the cache is destroyed.</para></tip>
</sect3>
<sect3 id="garqg"><title>See Also</title>
<para><olink targetptr="bdatg">ldap_memcache_flush</olink></para></sect3>
</sect2>
<sect2 id="bdatl"><title><function>ldap_memfree</function></title>
<para>The <function>ldap_memfree</function> function frees memory allocated
by an LDAP API function call.</para>
<sect3 id="garqc"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_memfree( void *p );</programlisting>
</sect3>
<sect3 id="garpf"><title>Parameters</title>
<table frame="topbot" id="garpx"><title><function>ldap_memfree</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>p</literal></para></entry>
<entry>
<para>Pointer to memory used by the LDAP library.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garoz"><title>Example</title>
<para><olink targetptr="ldap-memfree-example">Example 21&ndash;33</olink> frees
the memory allocated by the <olink targetptr="bdask">ldap_get_dn</olink> function.
</para>
<example id="ldap-memfree-example"><title>Using <function>ldap_memfree</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
char *dn;
LDAPMessage *entry;
...
/* Get the distinguished name (DN) for an entry */
dn = ldap_get_dn( ld, entry );
...
/* When you are finished working with the DN, free the memory allocated. */
ldap_memfree( dn );
...</programlisting>
</example>
</sect3>
<sect3 id="garpe"><title>See Also</title>
<para><olink targetptr="bdase">ldap_free_friendlymap</olink>,  <olink targetptr="bdasi">ldap_free_urldesc</olink>, <olink targetptr="bdatv">ldap_msgfree
</olink>, <olink targetptr="bdaxc">ldap_value_free</olink>, <olink targetptr="bdaxd">ldap_value_free_len</olink></para></sect3>
</sect2>
<sect2 id="bdatm"><title><function>ldap_modify</function></title>
<para>The <function>ldap_modify</function> function modifies an existing entry
in the directory asynchronously.</para>
<note><para>This is an older function included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdatn">ldap_modify_ext
</olink>  instead.</para></note>
<sect3 id="garpj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );</programlisting>
</sect3>
<sect3 id="garqq"><title>Parameters</title>
<table frame="topbot" id="garqi"><title><function>ldap_modify</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>mods</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
you want to modify.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garpo"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_modify</function> operation.
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>. For a list of possible result
codes for an LDAP modify operation, see <olink targetptr="bdato">ldap_modify_ext_s
</olink>.</para></sect3>
<sect3 id="garqk"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdatn">ldap_modify_ext
</olink> .</para></sect3>
<sect3 id="garqe"><title>Example</title>
<para><olink targetptr="ldap-modify-example">Example 21&ndash;34</olink> uses
the asynchronous <function>ldap_modify</function> function to modify the entry
for  <emphasis>Barbara Jensen</emphasis> in the directory. It makes the following
changes to the entry:</para>
<itemizedlist>
<listitem><para>Adds the <literal>homePhone</literal> attribute.</para>
</listitem>
<listitem><para>Changes the <literal>telephoneNumber</literal> attribute.</para>
</listitem>
<listitem><para>Removes the <literal>facsimileTelephoneNumber</literal> attribute.
</para></listitem>
</itemizedlist>
<example id="ldap-modify-example"><title>Using <function>ldap_modify</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";

/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "869-5309", NULL };

...
/* Specify each change in separate LDAPMod structures */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing entire attributes, you need to specify a NULL value
 * for the mod_values field. */

/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &amp;attribute1;
list_of_attrs[1] = &amp;attribute2;
list_of_attrs[2] = &amp;attribute3;
list_of_attrs[3] = NULL;
...
/* Set up the timeout period to wait for the "modify" operation */
tv.tv_sec = tv.tv_usec = 0;

/* Change the entry */
if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) {
  ldap_perror( ld, "ldap_modify" );
  return( 1 );
}

/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &amp;tv, &amp;result ) ) == 0 ) {
  ...
  /* do other work while waiting for the operation to complete */
  ...
}

/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modify" );
...</programlisting>
</example>
</sect3>
<sect3 id="garpi"><title>See Also</title>
<para><olink targetptr="bdatn">ldap_modify_ext</olink></para></sect3>
</sect2>
<sect2 id="bdatn"><title><function>ldap_modify_ext</function></title>
<para>The <function>ldap_modify_ext</function> function modifies an existing
entry in the directory asynchronously.</para>
<note><para><olink targetptr="bdatn">ldap_modify_ext</olink> is a new version
of the <olink targetptr="bdatm">ldap_modify</olink> function. If you are writing
a new LDAP client, use <olink targetptr="bdatn">ldap_modify_ext</olink>.</para>
</note>
<sect3 id="garpw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     int *msgidp );</programlisting>
</sect3>
<sect3 id="garpd"><title>Parameters</title>
<table frame="topbot" id="garpp"><title><function>ldap_modify_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>mods</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
you want to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation. To check the result of this operation, call <olink targetptr="bdauu">ldap_result
</olink>  and <olink targetptr="bdaun">ldap_parse_result</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garow"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garpc"><title>Description</title>
<para>The <function>ldap_modify_ext</function> modifies an entry in the directory
asynchronous; it does not directly return results. If you want the results
to be returned directly by the function, call the synchronous function  <olink targetptr="bdato">ldap_modify_ext_s</olink> instead. In order to get the results
of this LDAP modify operation, you need to call the <olink targetptr="bdauu">ldap_result
</olink> and the <olink targetptr="bdaun">ldap_parse_result</olink> functions.
To make changes to an entry to the directory, you need to specify the following
information:</para>
<itemizedlist>
<listitem><para>A unique DN identifying the new entry</para><para>Use the
 <literal>dn</literal> argument to specify the DN of the entry you want to
modify.</para></listitem>
<listitem><para>A set of attributes for the new entry</para><para>Create an <olink targetptr="bdalz">LDAPMod</olink> structure for changes that you want to make
to an attribute. Create an array of these <olink targetptr="bdalz">LDAPMod</olink> structures
and pass the array as the <literal>mods</literal> argument.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garpb"><title>See Also</title>
<para><olink targetptr="bdato">ldap_modify_ext_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
</olink>, <olink targetptr="bdalz">LDAPMod</olink></para></sect3>
</sect2>
<sect2 id="bdato"><title><function>ldap_modify_ext_s</function></title>
<para>The <function>ldap_modify_ext_s</function> modifies an existing entry
in the directory synchronously.</para>
<note><para><olink targetptr="bdato">ldap_modify_ext_s</olink> is a new version
of the <olink targetptr="bdatp">ldap_modify_s</olink> function. If you are
writing a new LDAP client, use <olink targetptr="bdato">ldap_modify_ext_s</olink>.
</para></note>
<sect3 id="garph"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods,
     LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="garov"><title>Parameters</title>
<table frame="topbot" id="garpt"><title><function>ldap_modify_ext_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>mods</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
you want to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garqj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garqh"><title>Description</title>
<para>The <function>ldap_modify_ext_s</function> modifies an entry in the
directory.  <function>ldap_modify_ext_s</function> is a synchronous function,
which directly returns the results of the operation. If you want to perform
other operations while waiting for the results of this operation, call the
asynchronous function  <olink targetptr="bdatn">ldap_modify_ext</olink> instead.</para>
<para>To make changes to an entry to the directory, you need to specify the
following information:</para>
<itemizedlist>
<listitem><para>A unique DN identifying the new entry</para><para>Use the
 <literal>dn</literal> argument to specify the DN of the entry that you want
to modify.</para></listitem>
<listitem><para>A set of attributes for the new entry</para><para>Create an <olink targetptr="bdalz">LDAPMod</olink> structure for change that you want to make
to an attribute. Create an array of these <olink targetptr="bdalz">LDAPMod</olink> structures
and pass the array as the <literal>mods</literal> argument.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garpk"><title>See Also</title>
<para><olink targetptr="bdatn">ldap_modify_ext</olink>,  <olink targetptr="bdalz">
LDAPMod</olink></para></sect3>
</sect2>
<sect2 id="bdatp"><title><function>ldap_modify_s</function></title>
<para>The <function>ldap_modify_s</function> function modifies an existing
entry in the directory synchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdato">ldap_modify_ext_s
</olink>  instead.</para></note>
<sect3 id="garpn"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );</programlisting>
</sect3>
<sect3 id="garoy"><title>Parameters</title>
<table frame="topbot" id="garqo"><title><function>ldap_modify_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>mods</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
you want to modify.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garpm"><title>Returns</title>
<para>For a list of possible result codes for an LDAP modify operation, see <olink targetptr="bdato">ldap_modify_ext_s</olink>.</para></sect3>
<sect3 id="garpq"><title>Description</title>
<para>Use the newer version of this function, <olink targetptr="bdato">ldap_modify_ext_s
</olink> .</para></sect3>
<sect3 id="garqd"><title>Example</title>
<para><olink targetptr="ldap-modify-s-example">Example 21&ndash;35</olink> uses
the synchronous <function>ldap_modify_s</function> function to makes the following
changes to the <literal>Barbara Jensen</literal> entry:</para>
<itemizedlist>
<listitem><para>Adds the <literal>homePhone</literal> attribute.</para>
</listitem>
<listitem><para>Changes the <literal>telephoneNumber</literal> attribute.</para>
</listitem>
<listitem><para>Removes the <literal>facsimileTelephoneNumber</literal> attribute.
</para></listitem>
</itemizedlist>
<example id="ldap-modify-s-example"><title>Using <function>ldap_modify_s</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPControl **srvrctrls, **clntctrls;

/* Distinguished name of the entry that you want to modify. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";

/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "869-5309", NULL };

...
/* Specify each change in separate LDAPMod structures */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing entire attributes, you need to specify a NULL value
 * for the mod_values or mod_bvalues field. */

/* Add the pointers to these LDAPMod structures to an array */
list_of_attrs[0] = &amp;attribute1;
list_of_attrs[1] = &amp;attribute2;
list_of_attrs[2] = &amp;attribute3;
list_of_attrs[3] = NULL;
...
/* Change the entry */
if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_modify_s" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garpg"><title>See Also</title>
<para><olink targetptr="bdato">ldap_modify_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdatq"><title><function>ldap_modrdn</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaus">ldap_rename</olink> instead.</para></note>
<sect3 id="bdatr"><title><function>ldap_modrdn_s</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaut">ldap_rename_s</olink> instead.</para></note>
</sect3>
</sect2>
<sect2 id="bdats"><title><function>ldap_modrdn2</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaus">ldap_rename</olink> instead.</para></note>
<para>The <function>ldap_modrdn2</function> function changes the relative
distinguished name (RDN) of an entry in the directory asynchronously.</para>
<sect3 id="garpu"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn,
     int deleteoldrdn );</programlisting>
</sect3>
<sect3 id="garos"><title>Parameters</title>
<table frame="topbot" id="garqn"><title><function>ldap_modrdn2</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>newrdn</literal></para></entry>
<entry>
<para>New RDN to assign to the entry.</para></entry>
</row>
<row>
<entry>
<para><literal>deleteoldrdn</literal></para></entry>
<entry>
<para>If this is a non-zero value, the old RDN is not retained as a value
in the modified entry. If <literal>0</literal>, the old RDN is retained as
an attribute in the modified entry.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garpv"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_modrdn2</function> operation.
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>. For a list of possible result
codes, see <olink targetptr="bdaus">ldap_rename</olink>.</para></sect3>
<sect3 id="garps"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaus">ldap_rename
</olink> .</para></sect3>
<sect3 id="garqw"><title>Example</title>
<para><olink targetptr="ldap-modrdn2-example">Example 21&ndash;36</olink> uses
the asynchronous <function>ldap_modrdn2</function> function to change the
RDN of an entry from <literal>uid=bjensen</literal> to <literal>uid=babs</literal>.
The code removes the existing RDN <literal>bjensen</literal> from the <literal>uid
</literal> attribute of the entry.</para>
<example id="ldap-modrdn2-example"><title>Using <function>ldap_modrdn2</function></title>
<programlisting>#include &lt;ldap-deprecated.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the entry that you want to rename. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";

/* New relative distinguished name (RDN) of the entry */
char *rdn = "uid=babs";
...
/* Set up the timeout period to wait for the "modify RDN" operation */
tv.tv_sec = tv.tv_usec = 0;

/* Rename the entry */
if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) {
  ldap_perror( ld, "ldap_modrdn2" );
  return( 1 );
}

/* Check to see if the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &amp;tv, &amp;result ) ) == 0 ) {
  ...
  /* do other work while waiting for the operation to complete */
  ...
}

/* Check the result to see if any errors occurred */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modrdn2" );
...</programlisting>
</example>
</sect3>
<sect3 id="garry"><title>See Also</title>
<para><olink targetptr="bdaus">ldap_rename</olink></para></sect3>
</sect2>
<sect2 id="bdatt"><title><function>ldap_modrdn2_s</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaut">ldap_rename_s</olink> instead.</para></note>
<para>The <function>ldap_modrdn2_s</function> function changes the relative
distinguished name (RDN) of an entry in the directory synchronously.</para>
<sect3 id="garra"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
 int ldap_modrdn2_s( LDAP *ld, const char *dn,
    const char *newrdn, int deleteoldrdn );</programlisting>
</sect3>
<sect3 id="garrh"><title>Parameters</title>
<table frame="topbot" id="garsa"><title><function>ldap_modrdn2_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>newrdn</literal></para></entry>
<entry>
<para>New RDN to assign to the entry.</para></entry>
</row>
<row>
<entry>
<para><literal>deleteoldrdn</literal></para></entry>
<entry>
<para>If this is a non-zero value, the old RDN is not retained as a value
in the modified entry. If <literal>0</literal>, the old RDN is retained as
an attribute in the modified entry.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garru"><title>Returns</title>
<para>For a list of possible result codes, see <olink targetptr="bdaut">ldap_rename_s
</olink> .</para></sect3>
<sect3 id="garqy"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdaut">ldap_rename_s
</olink> .</para></sect3>
<sect3 id="garre"><title>Example</title>
<para><olink targetptr="ldap-modrdn2-s-example">Example 21&ndash;37</olink> uses
the synchronous <function>ldap_modrdn2_s</function> function to change the
RDN of an entry from <literal>uid=bjensen</literal> to <literal>uid=babs</literal>.
The code removes the existing RDN <literal>babs</literal> from the <literal>uid</literal> attribute
of the entry.</para>
<example id="ldap-modrdn2-s-example"><title>Using <function>ldap_modrdn2_s</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;

/* Distinguished name of the entry that you want to rename. */
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";

/* New relative distinguished name (RDN) of the entry */
char *rdn = "uid=babs";
...
/* Rename the entry */
if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_modrdn2_s" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garqx"><title>See Also</title>
<para><olink targetptr="bdaut">ldap_rename_s</olink></para></sect3>
</sect2>
<sect2 id="bdatu"><title><function>ldap_mods_free</function></title>
<para>The <function>ldap_mods_free</function> function frees the  <olink targetptr="bdalz">LDAPMod</olink> structures that you&rsquo;ve allocated to
add or modify entries.</para>
<note><para>You need to call this function only if you&rsquo;ve allocated
memory for these structures yourself. For more information, see the <literal>ldap-extension.h
</literal>  header file.</para></note>
<sect3 id="garsb"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_mods_free( LDAPMod **mods, int freemods );</programlisting>
</sect3>
<sect3 id="garri"><title>Parameters</title>
<table frame="topbot" id="garrk"><title><function>ldap_mods_free</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>mods</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures.</para></entry>
</row>
<row>
<entry>
<para><literal>freemods</literal></para></entry>
<entry>
<para>If this is a non-zero value, frees the array of pointers as well as
the <olink targetptr="bdalz">LDAPMod</olink> structures. If <literal>0</literal>,
just frees the <olink targetptr="bdalz">LDAPMod</olink> structures.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garrz"><title>Example</title>
<para><olink targetptr="ldap-mods-free-example">Example 21&ndash;38</olink> allocates
memory for <olink targetptr="bdalz">LDAPMod</olink> structures and frees them
when done.</para>
<example id="ldap-mods-free-example"><title>Using <function>ldap_mods_free</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
char *dn;
int i, msgid;
LDAPMod **mods;
...
/* Construct the array of values to add */
mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * ));
if ( mods == NULL ) {
  fprintf( stderr, "Cannot allocate memory for mods array\n" );
}
for ( i = 0; i &lt; NMODS; i++ ) {
  if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) {
    fprintf( stderr, "Cannot allocate memory for mods element\n" );
    exit( 1 );
  }
}
...
/* Code for filling the structures goes here. */
...
/* Initiate the add operation */
if (( msgid = ldap_add( ld, dn, mods )) &lt; 0 ) {
  ldap_perror( ld, "ldap_add" );
  ldap_mods_free( mods, 1 );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdatv"><title><function>ldap_msgfree</function></title>
<para>The <function>ldap_msgfree</function> function frees the memory allocated
for a result by <olink targetptr="bdauu">ldap_result</olink> or  <olink targetptr="bdavb">ldap_search_s</olink>.</para>
<sect3 id="garqu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_msgfree( LDAPMessage *lm );</programlisting>
</sect3>
<sect3 id="garrf"><title>Parameters</title>
<table frame="topbot" id="garrv"><title><function>ldap_msgfree</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lm</literal></para></entry>
<entry>
<para>Pointer to the result to be freed from memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garrm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP bind operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
an LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAP
v3 search reference (a referral to another LDAP server) found during an LDAP
search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP modify operation.</para></listitem>
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP add operation.</para></listitem>
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP delete operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODRDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
result of an LDAP modify DN operation.</para></listitem>
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP compare operation.</para></listitem>
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP v3 extended operation.</para></listitem>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the operation times
out.</para></listitem>
<listitem><para><literal>-1</literal> indicates that the <literal>lm</literal> argument
is not a pointer to a valid <olink targetptr="bdaly">LDAPMessage</olink> structure.
</para></listitem>
<listitem><para>If unsuccessful, returns the LDAP error code for the operation.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garqz"><title>Example</title>
<para><olink targetptr="ldap-msgfree-example">Example 21&ndash;39</olink> frees
the results of a search.</para>
<example id="ldap-msgfree-example"><title>Using <function>ldap_msgfree</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *get_attr[] = { "cn", "mail", NULL };
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
                    get_attr, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}
...
/* Free the results when done */
ldap_msgfree( result );
...</programlisting>
</example>
</sect3>
<sect3 id="garro"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s
</olink></para></sect3>
</sect2>
<sect2 id="bdatw"><title><function>ldap_msgid</function></title>
<para>The <function>ldap_msgid</function> function determines the message
ID of a result obtained by calling <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink>.</para>
<sect3 id="garrn"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_msgid( LDAPMessage *lm );</programlisting>
</sect3>
<sect3 id="garqv"><title>Parameters</title>
<table frame="topbot" id="garrc"><title><function>ldap_msgid</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lm</literal></para></entry>
<entry>
<para>Pointer to the result to check.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garrd"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>The message ID if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garrx"><title>Example</title>
<para><olink targetptr="ldap-msgid-example">Example 21&ndash;40</olink> prints
the message ID from the result obtained from a synchronous LDAP search operation.
</para>
<example id="ldap-msgid-example"><title>Using <function>ldap_msgid</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
...
/* Perform a search */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
    NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Get and print the message ID */
if ( ldap_msgid( result ) != -1 ) {
  printf( "Message ID: %d\n" );
} else {
  printf( "An error occurred.\n" );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garrj"><title>See Also</title>
<para><olink targetptr="bdatx">ldap_msgtype</olink>, <olink targetptr="bdauu">ldap_result
</olink> , <olink targetptr="bdavb">ldap_search_s</olink></para></sect3>
</sect2>
<sect2 id="bdatx"><title><function>ldap_msgtype</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_msgtype</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_msgtype</function></primary>
</indexterm>
<para>The <function>ldap_msgtype</function> function determines the type of
result obtained by calling <olink targetptr="bdauu">ldap_result</olink> or
 <olink targetptr="bdavb">ldap_search_s</olink>.</para>
<sect3 id="garqr"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_msgtype( LDAPMessage *lm );</programlisting>
</sect3>
<sect3 id="garrg"><title>Parameters</title>
<table frame="topbot" id="garrs"><title><function>ldap_msgtype</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lm</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
to check.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garrp"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP bind operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
an LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAP
v3 search reference (a referral to another LDAP server) found during an LDAP
search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP modify operation.</para></listitem>
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP add operation.</para></listitem>
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP delete operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODRDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
result of an LDAP modify DN operation.</para></listitem>
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP compare operation.</para></listitem>
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP v3 extended operation.</para></listitem>
<listitem><para><literal>-1</literal> indicates that the <literal>lm</literal> argument
is not a pointer to a valid <olink targetptr="bdaly">LDAPMessage</olink> structure.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garqt"><title>Example</title>
<para><olink targetptr="ldap-msgtype-example">Example 21&ndash;41</olink> prints
the message type for a result obtained from a synchronous LDAP search operation.</para>
<example id="ldap-msgtype-example"><title>Using <function>ldap_msgtype</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgtype;
...
/* Perform a search */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
    NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Get and print the message type */
msgtype = ldap_msgtype( result );
if ( msgtype != -1 ) {
  printf( "Message type: %d\n", msgtype );
} else {
  printf( "An error occurred.\n" );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garrl"><title>See Also</title>
<para><olink targetptr="bdatw">ldap_msgid</olink>, <olink targetptr="bdauu">ldap_result
</olink> , <olink targetptr="bdavb">ldap_search_s</olink></para></sect3>
</sect2>
<sect2 id="bdaty"><title><function>ldap_multisort_entries</function></title>
<para>The <function>ldap_multisort_entries</function> function sorts a chain
of entries retrieved from an LDAP search call (<olink targetptr="bdavb">ldap_search_s
</olink> or <olink targetptr="bdauu">ldap_result</olink>) by either a specified
set of attributes in the entries or DN.</para>
<sect3 id="garrw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
     char **attr, LDAP_CMP_CALLBACK *cmp );</programlisting>
</sect3>
<sect3 id="garrb"><title>Parameters</title>
<table frame="topbot" id="garsc"><title><function>ldap_multisort_entries</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>chain</literal></para></entry>
<entry>
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Array of attributes to use for sorting the results. If <literal>NULL</literal>,
results are sorted by DN.</para></entry>
</row>
<row>
<entry>
<para><literal>cmp</literal></para></entry>
<entry>
<para>Comparison function used when sorting the values.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garqs"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if memory cannot be allocated by this
function. (The error code <errorcode>LDAP_NO_MEMORY</errorcode> is set in
the  <olink targetptr="bdakj">LDAP</olink> structure. To get the error code,
call the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function.)</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garrr"><title>Example</title>
<para><olink targetptr="ldap-multisort-entries-example">Example 21&ndash;42</olink> 
sorts entries first by the <literal>roomNumber</literal> attribute, then by
the <literal>telephoneNumber</literal> attribute.</para>
<example id="ldap-multisort-entries-example"><title>Using <function>ldap_multisort_entries
</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;string.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *attrs[3];
attrs[0] = "roomNumber";
attrs[1] = "telephoneNumber";
attrs[2] = NULL;
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
                    NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}

/* Sort the results, using strcasecmp */
if ( ldap_multisort_entries( ld, &amp;result, attrs, strcasecmp ) !=
     LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_multisort_entries" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garrt"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s
</olink> , <olink targetptr="bdavk">ldap_sort_entries</olink>,  <olink targetptr="bdakz">LDAP_CMP_CALLBACK</olink></para></sect3>
</sect2>
<sect2 id="bdatz"><title><function>ldap_name2template</function></title>
<para>The <function>ldap_name2template</function> function obtains a pointer
to the correct <literal>ldap_disptmpl</literal> structure.</para>
<sect3 id="garrq"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_disptmpl * ldap_name2template( char *name
    struct ldap_disptmpl *tmpllist );</programlisting>
</sect3>
<sect3 id="garsr"><title>Parameters</title>
<table frame="topbot" id="garsy"><title><function>ldap_name2template</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>name</literal></para></entry>
<entry>
<para>Name of the template.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gartl"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
</literal>  is configured.</para></listitem>
<listitem><para>Upon error:</para>
<itemizedlist>
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
to data that is newer than can be handled.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
with the format of the templates buffer or file.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
read.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garsh"><title>Description</title>
<para><function>ldap_name2template</function> obtains a pointer to the correct
 <literal>ldap_disptmpl</literal> structure. Links to templates can be defined
by name.</para></sect3>
</sect2>
<sect2 id="bdaua"><title><function>ldap_next_attribute</function></title>
<para>The <function>ldap_next_attribute</function> function returns the name
of the next attribute in an entry returned by <olink targetptr="bdary">ldap_first_entry
</olink>  or <olink targetptr="bdauc">ldap_next_entry</olink>.</para>
<sect3 id="garsx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry,
     BerElement *ber);</programlisting>
</sect3>
<sect3 id="gartz"><title>Parameters</title>
<table frame="topbot" id="gartu"><title><function>ldap_next_attribute</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
representing the entry returned by the <olink targetptr="bdary">ldap_first_entry</olink> or <olink targetptr="bdauc">ldap_next_entry</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>ber</literal></para></entry>
<entry>
<para>A pointer to a <olink targetptr="bdakh">BerElement</olink> allocated
to keep track of its current position. Pass this pointer to subsequent calls
to <function>ldap_next_attribute</function> to step through the entry's attributes.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garte"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the name of the next attribute in an
entry. When you are done using this data, you should free the memory by calling
the <olink targetptr="bdatl">ldap_memfree</olink> function.</para></listitem>
<listitem><para>If no more attributes exist in the entry, returns a <literal>NULL
</literal> .</para></listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gartf"><title>Description</title>
<para>The <olink targetptr="bdarw">ldap_first_attribute</olink> function returns
a pointer to a <olink targetptr="bdakh">BerElement</olink>. You use this pointer
with  <function>ldap_next_attribute</function> to iterate through the list
of elements. After the last call to <function>ldap_next_element</function>,
you should free the  <olink targetptr="bdakh">BerElement</olink> pointer using <olink targetptr="bdaqd">ldap_ber_free</olink>. When calling <olink targetptr="bdaqd">ldap_ber_free
</olink>, make sure to specify that the buffer is not freed (pass <literal>0</literal> for
the <literal>freebuf</literal> parameter).</para></sect3>
<sect3 id="garsm"><title>Example</title>
<para>See the example under <olink targetptr="bdarw">ldap_first_attribute</olink>.
</para></sect3>
<sect3 id="gartr"><title>See Also</title>
<para><olink targetptr="bdarw">ldap_first_attribute</olink>,  <olink targetptr="bdasn">ldap_getfirstfilter</olink>, <olink targetptr="bdauc">ldap_next_entry
</olink></para></sect3>
</sect2>
<sect2 id="bdaub"><title><function>ldap_next_disptmpl</function></title>
<para>The <function>ldap_next_disptmpl</function> function returns the next
template in a list.</para>
<sect3 id="gartt"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
    struct ldap_disptmpl *tmpl );;</programlisting>
</sect3>
<sect3 id="gartd"><title>Parameters</title>
<table frame="topbot" id="gartw"><title><function>ldap_next_disptmpl</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>Defines a template from the template list <parameter>tmpllist</parameter>.
A <literal>NULL</literal> pointer is returned if <parameter>tmpl</parameter> is
the last template in the list.</para></entry>
</row>
<row>
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures typically obtained by
calling <olink targetptr="bdata">ldap_init_templates</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garsg"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
</literal>  is configured.</para></listitem>
<listitem><para>Upon error:</para>
<itemizedlist>
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
to data that is newer than can be handled.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
allocation problem.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
with the format of the templates buffer or file.</para></listitem>
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
read.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garto"><title>Description</title>
<para><function>ldap_next_disptmpl</function> returns the template following
the previous one in the list of templates pointed to by the parameter <literal>tmpllistp
</literal>.  <literal>tmpllistp</literal> is typically obtained by calling <olink targetptr="bdata">ldap_init_templates</olink> .</para></sect3>
<sect3 id="garso"><title>See Also</title>
<para><olink targetptr="bdarx">ldap_first_disptmpl</olink></para></sect3>
</sect2>
<sect2 id="bdauc"><title><function>ldap_next_entry</function></title>
<para>The <function>ldap_next_entry</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the next directory entry in a chain of search results.</para>
<sect3 id="gartm"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );</programlisting>
</sect3>
<sect3 id="garsk"><title>Parameters</title>
<table frame="topbot" id="garsn"><title><function>ldap_next_entry</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>entry</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in a chain of search results.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garth"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the next  <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_ENTRY
</literal> in a chain of search results.</para></listitem>
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> are in the chain or if
the function is unsuccessful, returns a <literal>NULLMSG</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garua"><title>Description</title>
<para>The <function>ldap_next_entry</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the next directory entry in a chain of search results. You can use this function
in conjunction with the <olink targetptr="bdary">ldap_first_entry</olink> function
to iterate through the directory entries in a chain of search results. These
functions skip over any messages in the chain that do not have the type <literal>
LDAP_RES_SEARCH_ENTRY</literal> as messages containing directory entries have
the type <literal>LDAP_RES_SEARCH_ENTRY</literal>.</para></sect3>
<sect3 id="gartv"><title>See Also</title>
<para><olink targetptr="bdary">ldap_first_entry</olink></para></sect3>
</sect2>
<sect2 id="bdaud"><title><function>ldap_next_message</function></title>
<para>The <function>ldap_next_message</function> function returns a pointer
to the next <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
of search results.</para>
<sect3 id="gartc"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );</programlisting>
</sect3>
<sect3 id="garsu"><title>Parameters</title>
<table frame="topbot" id="garsd"><title><function>ldap_next_message</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>msg</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in a chain of search results.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garsq"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the next  <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain of search results.</para>
</listitem>
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
are in the chain or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garsp"><title>Description</title>
<para>The <function>ldap_next_message</function> function returns a pointer
to the next <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
of search results. You can use this function in conjunction with the <olink targetptr="bdarz">ldap_first_message</olink>  function to iterate through
the chain of search results. You can also call the <olink targetptr="bdatx">ldap_msgtype
</olink> function to determine if each message contains a matching entry (a
message of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> ) or a search
reference (a message of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>).</para>
</sect3>
<sect3 id="garsl"><title>See Also</title>
<para><olink targetptr="bdarz">ldap_first_message</olink>,  <olink targetptr="bdatx">ldap_msgtype</olink></para></sect3>
</sect2>
<sect2 id="bdaue"><title><function>ldap_next_reference</function></title>
<para>The <function>ldap_next_reference</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the next search reference in a chain of search results.</para>
<sect3 id="garsf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );</programlisting>
</sect3>
<sect3 id="gartq"><title>Parameters</title>
<table frame="topbot" id="garse"><title><function>ldap_next_reference</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>msg</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
in a chain of search results.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garst"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the pointer to the next  <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_REFERENCE
</literal> in a chain of search results.</para></listitem>
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> are in the chain
or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gartg"><title>Description</title>
<para>The <function>ldap_next_reference</function> function returns a pointer
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
the next search reference in a chain of search results. You can use this function
in conjunction with the <olink targetptr="bdasa">ldap_first_reference</olink> function
to iterate through the search references in a chain of search results.</para>
<para>These functions skip over any messages in the chain that do not have
the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>. Messages containing
search references have the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>,
continuation references as specified in LDAPv3 that are stored as referral
entries. Like a referral, each continuation reference itself may contain a
number of URLs assumed to be equivalent, and the client should use one of
those URLs.</para></sect3>
<sect3 id="garsz"><title>See Also</title>
<para><olink targetptr="bdasa">ldap_first_reference</olink></para></sect3>
</sect2>
<sect2 id="bdauf"><title><function>ldap_next_searchobj</function></title>
<para>The <function>ldap_next_searchobj</function> function returns the following
search preference in a defined list.</para>
<sect3 id="garty"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 struct ldap_searchobj * ldap_next_searchobj
    ( struct ldap_searchobj *sollist, struct ldap_searchobj *so );</programlisting>
</sect3>
<sect3 id="garsi"><title>Parameters</title>
<table frame="topbot" id="garsw"><title><function>ldap_next_searchobj</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sollist</literal></para></entry>
<entry>
<para>Pointer to a list of data structures, typically obtained by calling
 <olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>so</literal></para></entry>
<entry>
<para>Pointer to the most recent search object returned in the template list
 <literal>sollist</literal>. The search object returned by <function>ldap_next_searchobj
</function> follows this one.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gartb"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to an <literal>ldap_searchobj</literal> structure.
</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer is returned if <literal>so</literal> is
the last entry in the list.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garts"><title>Description</title>
<para>The search object returned by <function>ldap_next_searchobj</function> follows
the one defined by the <literal>so</literal> parameter.</para></sect3>
<sect3 id="garsv"><title>See Also</title>
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>,  <olink targetptr="bdasb">ldap_first_searchobj</olink></para></sect3>
</sect2>
<sect2 id="bdaug"><title><function>ldap_next_tmplcol</function></title>
<para>The <function>ldap_next_tmplcol</function> function returns a pointer
to the following item (in the column) within a template.</para>
<sect3 id="gartj"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
    struct ldap_tmplitem *row, struct ldap_tmplitem *col );</programlisting>
</sect3>
<sect3 id="gartk"><title>Parameters</title>
<table frame="topbot" id="gartn"><title><function>ldap_next_tmplcol</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>The name of the template to be retrieved.</para></entry>
</row>
<row>
<entry>
<para><literal>row</literal></para></entry>
<entry>
<para>The row in which the item is to be retrieved from.</para></entry>
</row>
<row>
<entry>
<para><literal>col</literal></para></entry>
<entry>
<para>The column in which the item is to be retrieved from.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garss"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer on error or if <literal>col</literal> was
the last item.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gartp"><title>Description</title>
<para><function>ldap_next_tmplcol</function> returns a pointer to the next
item (in the column) of the row, defined by <literal>row</literal>, within
the template defined by <literal>tmpl</literal>.</para></sect3>
<sect3 id="garti"><title>See Also</title>
<para><olink targetptr="bdasc">ldap_first_tmplcol</olink></para></sect3>
</sect2>
<sect2 id="bdauh"><title><function>ldap_next_tmplrow</function></title>
<para>The <function>ldap_next_tmplrow</function> function returns a pointer
to the following row in a template.</para>
<sect3 id="garta"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
    struct ldap_tmplitem *row );</programlisting>
</sect3>
<sect3 id="garsj"><title>Parameters</title>
<table frame="topbot" id="garub"><title><function>ldap_next_tmplrow</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>The name of the template to be retrieved.</para></entry>
</row>
<row>
<entry>
<para><literal>row</literal></para></entry>
<entry>
<para>The row in the template to be retrieved.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gartx"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvy"><title>Description</title>
<para><function>ldap_next_tmplrow</function> returns a pointer to the row
that follows the one defined by <literal>row</literal> in the template defined
by <literal>tmpl</literal> .</para></sect3>
</sect2>
<sect2 id="bdaui"><title><function>ldap_oc2template</function></title>
<para>The <function>ldap_oc2template</function> function obtains a pointer
to the correct <literal>ldap_disptmpl</literal> structure.</para>
<sect3 id="garvr"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 struct ldap_disptmpl * ldap_oc2template( char **oclist,
    struct ldap_disptmpl *tmpllist );</programlisting>
</sect3>
<sect3 id="garus"><title>Parameters</title>
<table frame="topbot" id="garvw"><title><function>ldap_oc2template</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>oclist</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of strings that contains
the values of the <literal>objectClass</literal> attribute of the entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>tmpllistp</literal></para></entry>
<entry>
<para>Pointer to a list of template data structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garvl"><title>Returns</title>
<itemizedlist>
<listitem><para>Pointer to the first template where all of the object classes
listed in one of the template's <literal>dt_oclist</literal> elements are
contained in  <literal>oclist</literal>.</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer if no appropriate template
is found.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvb"><title>Description</title>
<para><function>ldap_oc2template</function>searches <literal>tmpllist</literal> for
the best template to use to display an entry that has a specific set of  <literal>
objectClass</literal> values.</para></sect3>
</sect2>
<sect2 id="bdauj"><title><function>ldap_open</function></title>
<note><para>This function is deprecated and should not be used. Use <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init</olink> (IPv6)
instead.</para></note>
<para>The <function>ldap_open</function> function opens a connection to an
LDAP server and allocates an <olink targetptr="bdakj">LDAP</olink> structure
which is used to identify the connection and maintain per-connection information.
</para>
<sect3 id="garui"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
 ldap_open( const char *host, int port );</programlisting>
</sect3>
<sect3 id="garuv"><title>Parameters</title>
<table frame="topbot" id="garvo"><title><function>ldap_open</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>host</literal></para></entry>
<entry>
<para>The hostname on which the LDAP server is running. It may contain a blank-separated
list of hosts to try to connect to, and each host may optionally be of the
form  <replaceable>host</replaceable>:<replaceable>port</replaceable>. If
present, <replaceable>port</replaceable>  overrides the port parameter. Upon
successfully making a connection to an LDAP server, <function>ldap_open</function> returns
a  pointer  to  an  <olink targetptr="bdakj">LDAP</olink> structure, which
should be passed to subsequent calls <olink targetptr="bdaqe">ldap_bind</olink>, <olink targetptr="bdauy">ldap_search</olink></para></entry>
</row>
<row>
<entry>
<para><literal>port</literal></para></entry>
<entry>
<para>The port number to which to connect. If the default IANA-assigned port
of 389 is desired, <literal>LDAP_PORT</literal> should be specified as the
value of port.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garuc"><title>Description</title>
<para>Please use a newer version of this function, <olink targetptr="bdasv">ldap_init
</olink> or  <olink targetptr="bdaxr">prldap_init</olink> (IPv6).</para></sect3>
</sect2>
<sect2 id="ldap-parse-authzid-control"><title><function>ldap_parse_authzid_control
</function></title>
<para>The <function>ldap_parse_authzid_control</function> function parses
the authorization identity bind response control retrieved from the server
to extract the authorization ID.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_authzid_control( LDAP *ld,
    LDAPControl **ctrlp, char **authzid );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgdxa"><title><function>ldap_parse_authzid_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
retrieved from the server.</para></entry>
</row>
<row>
<entry>
<para><parameter>authzid</parameter></para></entry>
<entry>
<para>Pointer to string holding the authorization ID.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
can be found in the response returned from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-create-authzid-control">ldap_create_authzid_control</olink></para>
</sect3>
</sect2>
<sect2 id="bdauk"><title><function>ldap_parse_entrychange_control</function></title>
<para>The <function>ldap_parse_entrychange_control</function> function examines
a list of controls returned from a persistent search operation, retrieves
an entry change control, and parses that control for information (such as
the type of change made to the entry and the change number).</para>
<note><para>This function implements an extension to the LDAP v3. Entry change
notification is an optional feature; it may not be supported on all LDAP servers.
Call this function when interacting with LDAP servers that support this LDAP
v3 extension.</para></note>
<sect3 id="garvf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_parse_entrychange_control( LDAP *ld,
     LDAPControl **ctrls, int *chgtypep, char **prevdnp,
     int *chgnumpresentp, long *chgnump );</programlisting>
</sect3>
<sect3 id="garvx"><title>Parameters</title>
<table frame="topbot" id="garuj"><title><function>ldap_parse_entrychange_control</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>ctrlp</literal></para></entry>
<entry>
<para>An array of controls returned by the server. You obtain these controls
by calling the <olink targetptr="bdasl">ldap_get_entry_controls</olink> function
on an entry returned by the server.</para></entry>
</row>
<row>
<entry>
<para><literal>changetypes</literal></para></entry>
<entry>
<para>Pointer to an integer specifying the type of change made to the entry.
This field can have one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_CHANGETYPE_ADD</literal> specifies that the
entry was added to the directory.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_DELETE</literal> specifies that the
entry was deleted from the directory.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_MODIFY</literal> specifies that the
entry was modified.</para></listitem>
<listitem><para><literal>LDAP_CHANGETYPE_MODDN</literal> specifies that the
DN or RDN of the entry was changed (a modify RDN or modify DN operation was
performed).</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>prevdnp</literal></para></entry>
<entry>
<para>Pointer to the previous DN of the entry, if the <literal>changetypes</literal> argument
is <literal>LDAP_CHANGETYPE_MODDN</literal>. If the <literal>changetypes</literal> argument
has a different value, this argument is set to <literal>NULL</literal>. When
done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>chgnumpresentp</literal></para></entry>
<entry>
<para>Pointer to an integer specifying whether or not to the change number
is included in the control. The parameter can have the following possible
values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the change number is not
included.</para></listitem>
<listitem><para>A non-zero value specifies that the change number is included
and is available as the <literal>chgnump</literal> argument.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>chgnump</literal></para></entry>
<entry>
<para>Pointer to the change number identifying the change made to the entry,
if  <literal>chgnumpresentp</literal> points to a non-zero value.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garur"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when BER-decoding the control.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvg"><title>Description</title>
<para>The <function>ldap_parse_entrychange_control</function> function can
be called:</para>
<itemizedlist>
<listitem><para>To parse an entry returned from a persistent search operation
and retrieve an entry change control.</para></listitem>
<listitem><para>After receiving an entry from a persistent search and retrieving
the controls from the entry. Call <olink targetptr="bdasl">ldap_get_entry_controls
</olink>  to get the controls.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvn"><title>See Also</title>
<para><olink targetptr="bdara">ldap_create_persistentsearch_control</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink></para></sect3>
</sect2>
<sect2 id="bdaul"><title><function>ldap_parse_extended_result</function></title>
<para>The <function>ldap_parse_extended_result</function> function parses
the results of an LDAP extended operation and retrieves the object identifier
(OID) and data returned by the server.</para>
<note><para>This function implements an extension to the LDAP v3. Extended
operations might not be supported on all LDAP servers. Call this function
only when interacting with LDAP servers that support this LDAP v3 extension.</para>
</note>
<sect3 id="garuf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
     char **retoidp, struct berval **retdatap, int freeit );</programlisting>
</sect3>
<sect3 id="garuw"><title>Parameters</title>
<table frame="topbot" id="garun"><title><function>ldap_parse_extended_result</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
containing the results of an LDAP operation.</para></entry>
</row>
<row>
<entry>
<para><literal>retoidp</literal></para></entry>
<entry>
<para>Pointer to the OID returned by the server after performing the extended
operation. When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
</olink>  function.</para></entry>
</row>
<row>
<entry>
<para><literal>retdatap</literal></para></entry>
<entry>
<para>Pointer to the pointer to a <olink targetptr="bdakg">berval</olink> structure
containing the data returned by the server after performing the extended operation.
When done, you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink> 
function.</para></entry>
</row>
<row>
<entry>
<para><literal>freeit</literal></para></entry>
<entry>
<para>Specifies whether or not to free the results of the operation (the  <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
The parameter can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the result should not
be freed.</para></listitem>
<listitem><para>A non-zero value specifies that the result should be freed.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garvu"><title>Returns</title>
<para>One of the following values, which indicates the result of parsing the
server&rsquo;s response:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>This value does not apply to the operation itself.</para></note>
</sect3>
<sect3 id="garvv"><title>Description</title>
<para><function>ldap_parse_extended_result</function> parses the server&rsquo;s
response to an extended operation. After you call the <olink targetptr="bdaru">ldap_extended_operation
</olink>  and the <olink targetptr="bdauu">ldap_result</olink> functions,
you can pass the results to <function>ldap_parse_extended_result</function>.
This function gets the following data from the server&rsquo;s response:</para>
<itemizedlist>
<listitem><para>The extended operation OID received from the server is passed
back as the retoidp argument.</para></listitem>
<listitem><para>The data received from the server is passed back in the  <olink targetptr="bdakg">berval</olink> structure as the <literal>retdatap</literal> argument.
</para></listitem>
<listitem><para>The LDAP result code for the LDAP extended operation is placed
in the <literal>ld</literal> structure. You can get the result code by calling
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para><para>For
a list of possible result codes for an LDAP extended operation, see <olink targetptr="bdarv">ldap_extended_operation_s</olink> .</para></listitem>
</itemizedlist>
<note><para>The LDAP server must support the extended operation. &cnDirectoryServer; supports
a server plug-in interface that you can use to add support for extended operations.
</para></note>
</sect3>
<sect3 id="garuo"><title>See Also</title>
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>,  <olink targetptr="bdasq">ldap_get_lderrno</olink></para></sect3>
</sect2>
<sect2 id="ldap-parse-passwd"><title><function>ldap_parse_passwd</function></title>
<para>The <function>ldap_parse_passwd</function> function lets you examine
the result of an LDAP Password Modify extended operation to obtain the password
generated by the server when you reset a password without providing a new
password value.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result,
    struct berval *genpasswd );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgovaa"><title><function>ldap_parse_passwd</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>result</parameter></para></entry>
<entry>
<para>Pointer to the message retrieved using the message ID from <olink targetptr="ldap-passwd">ldap_passwd</olink>.</para></entry>
</row>
<row>
<entry>
<para><parameter>genpasswd</parameter></para></entry>
<entry>
<para>Pointer to the BER value structure to hold the password generated by
the server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated for the authorization identity.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3.</para><para>Make sure that you
set the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="ldap-parse-passwd-result"><title><function>ldap_parse_passwd_result</function></title>
<para>The <function>ldap_parse_passwd_result</function> function lets you
examine the result of an LDAP Password Modify extended operation to obtain
the password generated by the server when you reset a password without providing
a new password value.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp,
    struct timeval *timeout, struct berval *genpasswd );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgovaaa"><title><function>ldap_parse_passwd_result</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>msgidp</parameter></para></entry>
<entry>
<para>Pointer to the message ID retrieved using <olink targetptr="ldap-passwd">ldap_passwd
</olink>.</para></entry>
</row>
<row>
<entry>
<para><parameter>timeout</parameter></para></entry>
<entry>
<para>Specifies a maximum interval to wait for the selection to complete.
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
select blocks indefinitely. To effect a poll, the <parameter>timeout</parameter> parameter
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
timeval</structname> structure.</para></entry>
</row>
<row>
<entry>
<para><parameter>genpasswd</parameter></para></entry>
<entry>
<para>Pointer to the BER value structure to hold the password generated by
the server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated for the authorization identity.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3.</para><para>Make sure that you
set the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="ldap-parse-pwdpolicy-control"><title><function>ldap_parse_pwdpolicy_control
</function></title>
<para>The <function>ldap_parse_pwdpolicy_control</function> function parses
information about the password policy relative to a user account contained
in a control returned with a bind, add, modify, or compare result after the <olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control</olink> is
used to create a request control sent to the server. The <function>ldap_parse_pwdpolicy_control
</function> function populates an <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure.
</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_pwdpolicy_control( LDAP *ld,
    LDAPControl **ctrlp, LDAPpwdpolicy *pp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgdx"><title><function>ldap_parse_pwdpolicy_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
retrieved from the server.</para></entry>
</row>
<row>
<entry>
<para><parameter>pp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure
to hold the information about password policy.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
can be found in the response returned from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-create-pwdpolicy-control">ldap_create_pwdpolicy_control
</olink>, <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink></para></sect3>
</sect2>
<sect2 id="bdaum"><title><function>ldap_parse_reference</function></title>
<para>The <function>ldap_parse_reference</function> function parses search
references from the results received from an LDAP server.</para>
<note><para>Search references are part of the LDAP v3. When calling this function,
make sure that you are working with a server that supports the LDAP v3.</para>
</note>
<sect3 id="garvh"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
     char ***referralsp, LDAPControl ***serverctrlsp,
     int freeit );</programlisting>
</sect3>
<sect3 id="garvp"><title>Parameters</title>
<table frame="topbot" id="garvd"><title><function>ldap_parse_reference</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>ref</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>referralsp</literal></para></entry>
<entry>
<para>Pointer to an array of strings representing the referrals found by an
LDAP search operation and returned by the server (applicable only if the LDAP
operation was a search operation). When done, you can free this by calling
the  <olink targetptr="bdaxc">ldap_value_free</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrlsp</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
which represent the LDAP v3 server controls returned by the server. When done,
you can free this by calling the <olink targetptr="bdaqt">ldap_controls_free</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>freeit</literal></para></entry>
<entry>
<para>Specifies whether or not to free the results of the operation (the  <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
The parameter can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the result should not
be freed.</para></listitem>
<listitem><para>A non-zero value specifies that the result should be freed.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garug"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvz"><title>Description</title>
<para>The <function>ldap_parse_reference</function> function parses the referral
URLs from an <olink targetptr="bdaly">LDAPMessage</olink> structure of the
type  <literal>LDAP_RES_SEARCH_REFERENCE</literal>, continuation references
as specified in LDAPv3 that are stored as referral entries. Like a referral,
each continuation reference itself may contain a number of URLs assumed to
be equivalent, and the client should use one of those URLs.</para></sect3>
</sect2>
<sect2 id="bdaun"><title><function>ldap_parse_result</function></title>
<para>The <function>ldap_parse_result</function> function parses the results
of an LDAP operation received from an LDAP server.</para>
<sect3 id="garuy"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
     int *errcodep, char **matcheddnp, char **errmsgp,
     char ***referralsp, LDAPControl ***serverctrlsp, int freeit);</programlisting>
</sect3>
<sect3 id="garux"><title>Parameters</title>
<table frame="topbot" id="garvt"><title><function>ldap_parse_result</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
containing the results of an LDAP operation.</para></entry>
</row>
<row>
<entry>
<para><literal>errcodep</literal></para></entry>
<entry>
<para>Pointer to the LDAP result code specifying the result of the operation.</para>
</entry>
</row>
<row>
<entry>
<para><literal>matcheddnp</literal></para></entry>
<entry>
<para>Pointer to a string specifying the portion of a DN that finds an existing
entry (in cases where the server cannot find the entry specified by a DN).
When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>errmsgp</literal></para></entry>
<entry>
<para>Pointer to an additional error message string sent from the server.
When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>referralsp</literal></para></entry>
<entry>
<para>Pointer to an array of strings representing the referrals returned by
the server. When done, you can free this by calling the <olink targetptr="bdaxc">
ldap_value_free</olink>  function.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrlsp</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
which represent the LDAPv3 server controls returned by the server. When done,
you can free this by calling the <olink targetptr="bdaqt">ldap_controls_free</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>freeit</literal></para></entry>
<entry>
<para>Specifies whether or not to automatically free the results of the operation
(the <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the
 <literal>res</literal> argument). The parameter can have the following possible
values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the result should not
be freed.</para></listitem>
<listitem><para>A non-zero value specifies that the result should be freed.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garuq"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_RESULTS_RETURNED</errorcode> if the specified <olink targetptr="bdaly">LDAPMessage</olink> structure does not contain the result
of an LDAP operation (for example, if it contains an entry, search reference,
or chain of search results instead of the result of an LDAP operation).</para>
</listitem>
<listitem><para><errorcode>LDAP_MORE_RESULTS_TO_RETURN</errorcode> if the
result in the <olink targetptr="bdaly">LDAPMessage</olink> structure is part
of a chain of results and the last result is not included.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvj"><title>Description</title>
<para>The <function>ldap_parse_result</function> function parses the results
of an LDAP operation (received from an LDAP server) and retrieves:</para>
<itemizedlist>
<listitem><para>The LDAP result code that indicates the result of the LDAP
operation (<literal>errcodep</literal>).</para></listitem>
<listitem><para>An additional error message (<literal>optional</literal>)
sent by the server (<literal>errmsgp</literal>).</para></listitem>
<listitem><para>The portion of the DN that finds an entry, if the server is
unable to find an entry from a DN that you specify (<literal>matcheddnp</literal>).
</para></listitem>
<listitem><para>A set of referrals, if the server does not contain the entries
that you&rsquo;ve specified and if the server is configured to refer clients
to other servers (<literal>referralsp</literal>).</para></listitem>
<listitem><para>A set of server response controls that are relevant to the
operation (<literal>serverctrlsp</literal>).</para><para>Calling this function
creates an array of <olink targetptr="bdala">LDAPControl</olink> structures
that you can pass to subsequent API functions (such as the <olink targetptr="bdaup">ldap_parse_sort_control</olink> function.</para></listitem>
</itemizedlist>
<note><para>This function is not intended to be used to parse entries and
search references. Use the <olink targetptr="bdatx">ldap_msgtype</olink> function
to determine the type of result contained in the <olink targetptr="bdaly">LDAPMessage
</olink> structure. If the result is an entry returned as a search result,
call the  <olink targetptr="bdary">ldap_first_entry</olink> function to retrieve
the entry. If the result is a search reference, call the <olink targetptr="bdaum">
ldap_parse_reference</olink> function to retrieve the reference.</para></note>
</sect3>
<sect3 id="garuh"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink></para></sect3>
</sect2>
<sect2 id="bdauo"><title><function>ldap_parse_sasl_bind_result</function></title>
<para>The <function>ldap_parse_sasl_bind_result</function> function parses
the results of an LDAP SASL bind operation and retrieves data returned by
the server.</para>
<note><para>SASL authentication is part of the LDAP v3. When calling this
function, make sure that you are working with a server that supports the LDAP
v3.</para></note>
<sect3 id="garud"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
     struct berval **servercredp, int freeit );</programlisting>
</sect3>
<sect3 id="garvm"><title>Parameters</title>
<table frame="topbot" id="garum"><title><function>ldap_parse_sals_bind_result</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
containing the results of an LDAP operation.</para></entry>
</row>
<row>
<entry>
<para><literal>servercredp</literal></para></entry>
<entry>
<para>Pointer to a pointer to an <olink targetptr="bdakg">berval</olink> structure
containing any challenge or credentials returned by the server. When done,
you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>freeit</literal></para></entry>
<entry>
<para>Specifies whether or not to free the results of the operation (the  <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
The parameter can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the result should not
be freed.</para></listitem>
<listitem><para>A non-zero value specifies that the result should be freed.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garue"><title>Returns</title>
<para>One of the following values, which indicates the result of parsing the
server&rsquo;s response:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>This value does not apply to the SASL bind operation itself)</para>
</note>
</sect3>
<sect3 id="garve"><title>Description</title>
<para>After you call the <olink targetptr="bdauw">ldap_sasl_bind</olink> function
and the <olink targetptr="bdauu">ldap_result</olink> function, you can pass
the results to <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> for
parsing. This function gets the following data from the server&rsquo;s response:</para>
<itemizedlist>
<listitem><para>The challenge or credentials sent back from the server are
passed back in the <olink targetptr="bdakg">berval</olink> structure as the <literal>
servercredp</literal>  argument.</para></listitem>
<listitem><para>The LDAP result code for the SASL bind operation is placed
in the  <literal>ld</literal> structure. You can get the result code by calling
the  <olink targetptr="bdasq">ldap_get_lderrno</olink> function. (If the result
code is <errorcode>LDAP_SASL_BIND_IN_PROGRESS</errorcode> , you can call <olink targetptr="bdauw">ldap_sasl_bind</olink> again to send a response to the server&rsquo;s
challenge and call  <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> again to get the next
challenge from the server. For a list of possible result codes for an LDAP
SASL bind operation, see <olink targetptr="bdauw">ldap_sasl_bind</olink>.</para>
</listitem>
</itemizedlist>
<note><para>The LDAP server must support authentication through SASL mechanisms. &cnDirectoryServer; supports
a plug-in interface that you can use to add SASL support to the server.</para>
</note>
</sect3>
<sect3 id="garva"><title>See Also</title>
<para><olink targetptr="bdauw">ldap_sasl_bind</olink>,  <olink targetptr="bdasq">
ldap_get_lderrno</olink></para></sect3>
</sect2>
<sect2 id="bdaup"><title><function>ldap_parse_sort_control</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_parse_sort_control</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_parse_sort_control</function></primary>
</indexterm>
<para>The <function>parse_sort_control</function> function parses the result
returned from a search operation that used a server control for sorting search
results.</para>
<note><para>This function implements an extension to the LDAP v3. Server-side
sorting is an optional feature; it may not be supported on all LDAP servers.
Call this function when interacting with LDAP servers that support this LDAP
v3 extension</para></note>
<sect3 id="garvc"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
     unsigned long *result, char **attribute );</programlisting>
</sect3>
<sect3 id="garuz"><title>Parameters</title>
<table frame="topbot" id="garup"><title><function>ldap_parse_sort_control</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>ctrls</literal></para></entry>
<entry>
<para>An array of controls returned by the server. You obtain these controls
by calling the <olink targetptr="bdaun">ldap_parse_result</olink> function
on the set of results returned by the server.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Pointer to the sort control result code retrieved by this function.</para>
</entry>
</row>
<row>
<entry>
<para><literal>attribute</literal></para></entry>
<entry>
<para>If the sorting operation fails, the function sets this to point to the
name of the attribute that caused the failure. When done, you can free this
by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garul"><title>Returns</title>
<para>One of the following values, which indicates the result of parsing the
server&rsquo;s response:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
can be found in the response returned from the server.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvk"><title>Description</title>
<para>Call the <function>ldap_parse_sort_control</function> function as part
of the process of retrieving sorted search results from a server. First, though,
call <olink targetptr="bdauu">ldap_result</olink> to get the results, and
 <olink targetptr="bdaun">ldap_parse_result</olink> to parse the server controls
from the results.</para></sect3>
<sect3 id="garvi"><title>See Also</title>
<para><olink targetptr="bdare">ldap_create_sort_control</olink></para></sect3>
</sect2>
<sect2 id="ldap-parse-userstatus-control"><title><function>ldap_parse_userstatus_control
</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_parse_userstatus_control</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_parse_userstatus_control</function></primary>
</indexterm>
<para>The <function>ldap_parse_userstatus_control</function> function parses
information about the status of a user account contained in a control returned
with an entry resulting from a search request that included the control created
with <olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
</olink>. The <function>ldap_parse_userstatus_control</function> function
populates an <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld,
    LDAPControl **ctrlp, LDAPuserstatus *us );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgdl"><title><function>ldap_parse_userstatus_control</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>ctrlp</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
retrieved with <olink targetptr="bdasl">ldap_get_entry_controls</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><parameter>us</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure
to hold the information about account status.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
can be found in the response returned from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3><title>See Also</title>
<para><olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
</olink>, <olink targetptr="ldapuserstatus">LDAPuserstatus</olink></para>
</sect3>
</sect2>
<sect2 id="ldap-parse-whoami"><title><function>ldap_parse_whoami</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_parse_whoami</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_parse_whoami</function></primary>
</indexterm>
<para>The <function>ldap_parse_whoami</function> function retrieves the authorization
identity from the result of an asynchronous Who am I? extended operation request.
</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, 
 LDAPMessage *result, char **authzid );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgova"><title><function>ldap_parse_whoami</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>result</parameter></para></entry>
<entry>
<para>Pointer to the message retrieved using the message ID from <olink targetptr="ldap-whoami">ldap_whoami</olink>.</para></entry>
</row>
<row>
<entry>
<para><parameter>authzid</parameter></para></entry>
<entry>
<para>Pointer to the string to hold the authorization identity retrieved for
the connection.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated for the authorization identity.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3. Make sure that you set the version
of your LDAP client to version 3 before calling this function.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="ldap-parse-whoami-result"><title><function>ldap_parse_whoami_result</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_parse_whoami_result</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_parse_whoami_result</function></primary>
</indexterm>
<para>The <function>ldap_parse_whoami_result</function> function retrieves
the authorization identity from the result of an asynchronous Who am I? extended
operation request.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp,
    struct timeval *timeout, char **authzid );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgov"><title><function>ldap_parse_whoami_result</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><parameter>ld</parameter></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><parameter>msgidp</parameter></para></entry>
<entry>
<para>Pointer to the message ID retrieved using <olink targetptr="ldap-whoami">ldap_whoami
</olink>.</para></entry>
</row>
<row>
<entry>
<para><parameter>timeout</parameter></para></entry>
<entry>
<para>Specifies a maximum interval to wait for the selection to complete.
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
select blocks indefinitely. To effect a poll, the <parameter>timeout</parameter> parameter
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
timeval</structname> structure.</para></entry>
</row>
<row>
<entry>
<para><parameter>authzid</parameter></para></entry>
<entry>
<para>Pointer to the string to hold the authorization identity retrieved for
the connection.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated for the authorization identity.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3. Make sure that you set the version
of your LDAP client to version 3 before calling this function.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdauq"><title><function>ldap_parse_virtuallist_control</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_parse_virtuallist_control</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_parse_virtuallist_control</function></primary>
</indexterm>
<para>The <function>ldap_parse_virtuallist_control</function> function parses
the result returned from a search operation that used a server control for
virtual list views.</para>
<note><para>This function implements an extension to the LDAP v3. A <emphasis>virtual
list view</emphasis> is an optional LDAP server feature that may not be supported
on all LDAP servers.</para></note>
<sect3 id="garut"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_parse_virtuallist_control( LDAP *ld,
     LDAPControl **ctrls, unsigned long *target_posp,
     unsigned long *list_sizep, int *errcodep );</programlisting>
</sect3>
<sect3 id="garuu"><title>Parameters</title>
<table frame="topbot" id="garvq"><title><function>ldap_parse_virtuallist_control</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameters</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>ctrls</literal></para></entry>
<entry>
<para>An array of controls returned by the server. You obtain these controls
by calling the <olink targetptr="bdaun">ldap_parse_result</olink> function
on the set of results returned by the server.</para></entry>
</row>
<row>
<entry>
<para><literal>target_posp</literal></para></entry>
<entry>
<para>Pointer to an unsigned long that is set by the function. The function
sets this to the index or offset of the selected entry in the list of entries.</para>
</entry>
</row>
<row>
<entry>
<para><literal>list_sizep</literal></para></entry>
<entry>
<para>Pointer to an unsigned long that is set by the function. The function
sets this to the number of entries in the total number of entries in the entire
list (not just the subset).</para></entry>
</row>
<row>
<entry>
<para><literal>errcodep</literal></para></entry>
<entry>
<para>Pointer to the sort control result code retrieved by this function.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garwa"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded message.</para></listitem>
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
can be found in the response returned from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garuk"><title>Description</title>
<para>The <function>ldap_parse_virtuallist_control</function> function can
be called:</para>
<itemizedlist>
<listitem><para>As part of the process of retrieving a subset of entries from
a list when working with a virtual list view box.</para></listitem>
<listitem><para>After, calling <olink targetptr="bdauu">ldap_result</olink> to
get the results, and <olink targetptr="bdaun">ldap_parse_result</olink> to
parse the server controls from the results.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garvs"><title>See Also</title>
<para><olink targetptr="bdarg">ldap_create_virtuallist_control</olink></para>
</sect3>
</sect2>
<sect2 id="ldap-passwd"><title><function>ldap_passwd</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_passwd</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_passwd</function></primary>
</indexterm>
<para>The <function>ldap_passwd</function> asynchronous function allows you
to perform an LDAP Password Modify extended operation, as defined in <ulink
url="http://ietf.org/rfc/rfc3062.txt" type="text_url">RFC 3062</ulink>.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_passwd( LDAP *ld, struct berval *userid,
    struct berval *oldpasswd, struct berval *newpasswd,
    LDAPControl **serverctrls, LDAPControl **clientctrls,
    int *msgidp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgvv"><title><function>ldap_passwd</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>userid</literal></para></entry>
<entry>
<para>DN of the user whose password you want to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>oldpasswd</literal></para></entry>
<entry>
<para>Old password used before expiration.</para>
<para>If the password has not yet expired, this is the current password.</para>
</entry>
</row>
<row>
<entry>
<para><literal>newpasswd</literal></para></entry>
<entry>
<para>New password to use after modification</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this LDAP operation. If you
do not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this LDAP operation. If you
do not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer to be set to the message ID of the operation.</para>
<para>To check the result of this operation, call the <olink targetptr="bdauu">ldap_result
</olink> and <olink targetptr="ldap-parse-passwd">ldap_parse_passwd</olink> function,
or <olink targetptr="ldap-parse-passwd-result">ldap_parse_passwd_result</olink> function.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3.</para><para>Make sure that you
set the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="ldap-passwd-s"><title><function>ldap_passwd_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_passwd_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_passwd_s</function></primary>
</indexterm>
<para>The <function>ldap_passwd_s</function> synchronous function allows you
to perform an LDAP Password Modify extended operation, as defined in <ulink
url="http://ietf.org/rfc/rfc3062.txt" type="text_url">RFC 3062</ulink>.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_passwd_s( LDAP *ld, struct berval *userid,
    struct berval *oldpasswd, struct berval *newpasswd,
    struct berval *genpasswd, LDAPControl **serverctrls,
    LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgvva"><title><function>ldap_passwd</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>userid</literal></para></entry>
<entry>
<para>DN of the user whose password you want to modify.</para></entry>
</row>
<row>
<entry>
<para><literal>oldpasswd</literal></para></entry>
<entry>
<para>Old password used before expiration.</para>
<para>If the password has not yet expired, this is the current password.</para>
</entry>
</row>
<row>
<entry>
<para><literal>newpasswd</literal></para></entry>
<entry>
<para>New password to use after modification</para></entry>
</row>
<row>
<entry>
<para><literal>genpasswd</literal></para></entry>
<entry>
<para>New password generated by the server when an expired password is reset,
but no <literal>newpasswd</literal> value is provided.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this LDAP operation. If you
do not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this LDAP operation. If you
do not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the control.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
does not specify that it is using LDAP v3.</para><para>Make sure that you
set the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdaur"><title><function>ldap_perror</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_perror</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_perror</function></primary>
</indexterm>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdasq">ldap_get_lderrno</olink> instead.</para></note>
<para>The <function>ldap_perror</function> function prints, to standard output,
the last LDAP error message.</para>
<sect3 id="garwu"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
 void ldap_perror( LDAP *ld, const char *s );</programlisting>
</sect3>
<sect3 id="garxv"><title>Parameters</title>
<table frame="topbot" id="garws"><title><function>ldap_perror</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>Optional text to print out before printing the error message.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garwf"><title>Description</title>
<para>Use the newer version of this function, <olink targetptr="bdasq">ldap_get_lderrno
</olink> .</para></sect3>
<sect3 id="garwt"><title>Example</title>
<para><olink targetptr="ldap-perror-example">Example 21&ndash;43</olink> prints
out an error message if the search operation cannot complete successfully.</para>
<example id="ldap-perror-example"><title>Using <function>ldap_perror</function></title>
<programlisting>...
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
  get_attr, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
...</programlisting>
</example>
</sect3>
<sect3 id="garwv"><title>See Also</title>
<para><olink targetptr="bdasq">ldap_get_lderrno</olink>,  <olink targetptr="bdarq">ldap_err2string</olink>, <olink targetptr="bdauv">ldap_result2error
</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink></para></sect3>
</sect2>
<sect2 id="bdaus"><title><function>ldap_rename</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_rename</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_rename</function></primary>
</indexterm>
<para>The <function>ldap_rename</function> function changes the DN of an entry
in the directory asynchronously.</para>
<note><para><function>ldap_rename</function> is a new version of the  <olink targetptr="bdats">ldap_modrdn2</olink> function. If you are writing a new
LDAP client, you should call <function>ldap_rename</function>.</para></note>
<sect3 id="garwo"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn,
    const char *newparent, int deleteoldrdn,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     int *msgidp );</programlisting>
</sect3>
<sect3 id="garxu"><title>Parameters</title>
<table frame="topbot" id="garxx"><title><function>ldap_rename</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to rename.</para></entry>
</row>
<row>
<entry>
<para><literal>newrdn</literal></para></entry>
<entry>
<para>New Relative Distinguished Name (RDN) to assign to the entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>newparent</literal></para></entry>
<entry>
<para>DN of the new parent entry you want to move the entry under. Pass  <literal>
NULL</literal> if you do not want to move the entry to a different location
in the directory tree.</para></entry>
</row>
<row>
<entry>
<para><literal>deleteoldrdn</literal></para></entry>
<entry>
<para>Specifies whether or not the old RDN is retained as an attribute of
the entry. For example, an entry has the following values for the <literal>cn</literal> attribute:
</para>
<para><literal>cn: Barbara Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para>If you change the RDN to <literal>cn=Barbie Jensen</literal> and pass
 <literal>1</literal> as <literal>deleteoldrdn</literal>, the resulting entry
has the following values:</para>
<para><literal>cn: Barbie Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para>If instead you pass <literal>0</literal> as <literal>deleteoldrdn</literal>,
the <literal>Barbara Jensen</literal> value is not removed from the entry:</para>
<para><literal>cn: Barbie Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para><literal>cn: Barbara Jensen</literal></para>
<para>So, if this is a non-zero value, the old RDN is not retained as a value
in the entry. If <literal>0</literal>, the old RDN is retained as an attribute
in the entry.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this LDAP operation. If you
do not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this LDAP operation. If you
do not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation. To check the result of this operation, call the <olink targetptr="bdauu">ldap_result</olink>  and <olink targetptr="bdaun">ldap_parse_result
</olink> functions.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garwl"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garxk"><title>Description</title>
<para>The <function>ldap_rename</function> changes the DN of an entry in the
directory and allows you to move the entry under a different parent entry
in the directory tree.  <function>ldap_rename</function> is an asynchronous
function; it does not directly return results. In order to get the results
of the LDAP rename operation, you need to call the <olink targetptr="bdauu">ldap_result
</olink> function and the  <olink targetptr="bdaun">ldap_parse_result</olink> function.
If you want the results to be returned directly by the function, call the
synchronous function <olink targetptr="bdaut">ldap_rename_s</olink>  instead.</para>
</sect3>
<sect3 id="garwk"><title>See Also</title>
<para><olink targetptr="bdaut">ldap_rename_s</olink>,  <olink targetptr="bdauu">ldap_result
</olink>, <olink targetptr="bdaun">ldap_parse_result</olink></para></sect3>
</sect2>
<sect2 id="bdaut"><title><function>ldap_rename_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_rename_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_rename_s</function></primary>
</indexterm>
<para>The <function>ldap_rename_s</function> function changes the DN of an
entry in the directory synchronously.</para>
<note><para><function>ldap_rename_s</function> is a new version of the  <olink targetptr="bdatt">ldap_modrdn2_s</olink> function. If you are writing a new
LDAP client, you should call <function>ldap_rename_s</function>.</para></note>
<sect3 id="garxh"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn,
     const char *newparent, int deleteoldrdn,
     LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="garxt"><title>Parameters</title>
<table frame="topbot" id="garyd"><title><function>ldap_rename</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the entry to rename.</para></entry>
</row>
<row>
<entry>
<para><literal>newrdn</literal></para></entry>
<entry>
<para>New Relative Distinguished Name (RDN) to assign to the entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>newparent</literal></para></entry>
<entry>
<para>DN of the new parent entry you want to move the entry under. Pass  <literal>
NULL</literal> if you do not want to move the entry to a different location
in the directory tree.</para></entry>
</row>
<row>
<entry>
<para><literal>deleteoldrdn</literal></para></entry>
<entry>
<para>Specifies whether or not the old RDN is retained as an attribute of
the entry. For example, an entry has the following values for the <literal>cn</literal> attribute:
</para>
<para><literal>cn: Barbara Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para>If you change the RDN to <literal>cn=Barbie Jensen</literal> and pass
 <literal>1</literal> as <literal>deleteoldrdn</literal>, the resulting entry
has the following values:</para>
<para><literal>cn: Barbie Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para>If instead you pass <literal>0</literal> as <literal>deleteoldrdn</literal>,
the <literal>Barbara Jensen</literal> value is not removed from the entry:</para>
<para><literal>cn: Barbie Jensen</literal></para>
<para><literal>cn: Babs Jensen</literal></para>
<para><literal>cn: Barbara Jensen</literal></para>
<para>So, if this is a non-zero value, the old RDN is not retained as a value
in the entry. If <literal>0</literal>, the old RDN is retained as an attribute
in the entry.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garxj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated to decode the control returned by the server.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAPv3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garwq"><title>Description</title>
<para>The <function>ldap_rename_s</function> changes the DN of an entry in
the directory and allows you to move the entry under a different parent entry
in the directory tree. The function <function>ldap_rename_s</function> is
synchronous; it directly returns the results of the operation. If you want
to perform other operations while waiting for the results of this operation,
call the asynchronous function  <olink targetptr="bdaus">ldap_rename</olink>.</para>
</sect3>
<sect3 id="garxa"><title>See Also</title>
<para><olink targetptr="bdaus">ldap_rename</olink></para></sect3>
</sect2>
<sect2 id="bdauu"><title><function>ldap_result</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_result</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_result</function></primary>
</indexterm>
<para>The function <function>ldap_result</function> waits for and returns
the result of an LDAP operation initiated by one of the asynchronous LDAP
API functions.</para>
<sect3 id="garwz"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_result( LDAP *ld, int msgid, int all,
     struct timeval *timeout, LDAPMessage **result );</programlisting>
</sect3>
<sect3 id="garxg"><title>Parameters</title>
<table frame="topbot" id="garxy"><title><function>ldap_result</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>msgid</literal></para></entry>
<entry>
<para>Asynchronous functions return a unique message ID. This parameter takes
message ID of the operation for which you want the results. To check any operation,
pass  <literal>LDAP_RES_ANY</literal> as the value of this parameter.</para>
</entry>
</row>
<row>
<entry>
<para><literal>all</literal></para></entry>
<entry>
<para>Specifies how the results of a search are returned. This parameter can
have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the results are returned
one entry at a time, using separate calls to <function>ldap_result</function>.</para>
</listitem>
<listitem><para>A non-zero value specifies that all results are returned at
the same time (after the final search result is obtained by the library).</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>timeout</literal></para></entry>
<entry>
<para>Specifies a maximum interval to wait for the selection to complete.
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
select blocks indefinitely. To effect a poll, the <literal>timeout</literal> parameter
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
timeval</structname> structure.</para></entry>
</row>
<row>
<entry>
<para><literal>result</literal></para></entry>
<entry>
<para>Result of the operation. To interpret the results, pass this to the
LDAP parsing routines, such as <olink targetptr="bdauv">ldap_result2error</olink>,
 <olink targetptr="bdaun">ldap_parse_result</olink>, and <olink targetptr="bdary">
ldap_first_entry</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garwm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP bind operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
an LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAPv3
search reference (a referral to another LDAP server) found during an LDAP
search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP search operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP modify operation.</para></listitem>
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP add operation.</para></listitem>
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP delete operation.</para></listitem>
<listitem><para><literal>LDAP_RES_MODDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
result of an LDAP modify DN operation.</para></listitem>
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP compare operation.</para></listitem>
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the  <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
LDAP v3 extended operation.</para></listitem>
<listitem><para><literal>-1</literal> indicates that an error occurred. The
error code is set in the <olink targetptr="bdakj">LDAP</olink> structure.
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
</para></listitem>
<listitem><para><literal>0</literal> indicates that the operation has timed
out.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garwh"><title>See Also</title>
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqp">ldap_compare_ext
</olink> , <olink targetptr="bdari">ldap_delete_ext</olink>,  <olink targetptr="bdatn">ldap_modify_ext</olink>, <olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdawm">ldap_url_search
</olink></para></sect3>
</sect2>
<sect2 id="bdauv"><title><function>ldap_result2error</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_result2error</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_result2error</function></primary>
</indexterm>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use the
newer version, <olink targetptr="bdaun">ldap_parse_result</olink>.</para></note>
<para>The <function>ldap_result2error</function> function returns the corresponding
error code for a result produced by the <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdavb">ldap_search_s</olink> functions.</para>
<sect3 id="garxo"><title>Syntax</title>
<programlisting>#include &lt;ldap-deprecated.h>
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );</programlisting>
</sect3>
<sect3 id="garwy"><title>Parameters</title>
<table frame="topbot" id="garwn"><title><function>ldap_result2error</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>r</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
representing the results returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdauy">ldap_search</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>freeit</literal></para></entry>
<entry>
<para>Specifies whether or not the result should be freed after the error
code is extracted. The parameter can have the following possible values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the result should not
be freed.</para></listitem>
<listitem><para>A non-zero value specifies that the result should be freed.</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garxe"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, sets the error code and other error information
in the <olink targetptr="bdakj">LDAP</olink> structure and returns the error
code.</para></listitem>
<listitem><para>If unsuccessful, returns <errorcode>LDAP_PARAM_ERROR</errorcode>.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garxm"><title>Example</title>
<para>See <olink targetptr="bdauu">ldap_result</olink>.</para></sect3>
<sect3 id="garxi"><title>See Also</title>
<para><olink targetptr="bdaun">ldap_parse_result</olink>,  <olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdarq">ldap_err2string
</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavf">
ldap_set_lderrno</olink></para></sect3>
</sect2>
<sect2 id="bdauw"><title><function>ldap_sasl_bind</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_sasl_bind</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_sasl_bind</function></primary>
</indexterm>
<para>The <function>ldap_sasl_bind</function> function authenticates your
client to an LDAP server using an Simple Authentication and Security Layer
(SASL) mechanism.</para>
<note><para>The LDAP server must support authentication through SASL. &cnDirectoryServer; supports
a server plug-in interface that you can use to add SASL support to the server.</para>
</note>
<sect3 id="garxd"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_sasl_bind( LDAP *ld, const char *dn,
    const char *mechanism, const struct berval *cred,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     int *msgidp );</programlisting>
</sect3>
<sect3 id="garwd"><title>Parameters</title>
<table frame="topbot" id="garwb"><title><function>ldap_sasl_bind</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this to <literal>NULL</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>mechanism</literal></para></entry>
<entry>
<para>Name of the SASL mechanism that you want to use for authentication.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cred</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure containing
the credentials that you want to use for authentication.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation. To check the result of this operation, call <olink targetptr="bdauu">ldap_result
</olink>  and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> functions.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garxp"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
was sent successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request&mdash;for example, as a session preference&mdash;and
your LDAP client does not specify that it is using the LDAP v3. Make sure
that you set the version of your LDAP client to version 3 before calling this
function.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request to send to the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garwr"><title>Description</title>
<para>The <function>ldap_sasl_bind</function> function authenticates your
client to an LDAP server by using a specified SASL mechanism. <function>ldap_sasl_bind
</function> is an asynchronous function; it does not directly return results.
If you want the results to be returned directly by the function, call the
synchronous function  <olink targetptr="bdaux">ldap_sasl_bind_s</olink>. In
order to get the results of the LDAP SASL bind operation, call the <olink targetptr="bdauu">ldap_result</olink>, the  <olink targetptr="bdauo">ldap_parse_sasl_bind_result
</olink>, and the <olink targetptr="bdasq">ldap_get_lderrno</olink>  functions.</para>
</sect3>
<sect3 id="garxr"><title>See Also</title>
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauo">ldap_parse_sasl_bind_result
</olink> , <olink targetptr="bdasq">ldap_get_lderrno</olink>,  <olink targetptr="bdaux">ldap_sasl_bind_s</olink></para></sect3>
</sect2>
<sect2 id="bdaux"><title><function>ldap_sasl_bind_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_sasl_bind_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_sasl_bind_s</function></primary>
</indexterm>
<para>The <function>ldap_sasl_bind_s</function> function authenticates your
client to an LDAP server synchronously using an SASL mechanism.</para>
<note><para>The LDAP server must support authentication through SASL. &cnDirectoryServer; supports
a server plug-in interface that you can use to add SASL support to the server.</para><?Pub
Caret1></note>
<sect3 id="garwj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_sasl_bind_s( LDAP *ld, const char *dn,
    const char *mechanism, const struct berval *cred,
    LDAPControl **serverctrls, LDAPControl **clientctrls,
     struct berval **servercredp );</programlisting>
</sect3>
<sect3 id="garxn"><title>Parameters</title>
<table frame="topbot" id="garyb"><title><function>ldap_sasl_bind_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>dn</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this to <literal>NULL</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>mechanism</literal></para></entry>
<entry>
<para>Name of the SASL mechanism that you want to use for authentication.</para>
</entry>
</row>
<row>
<entry>
<para><literal>cred</literal></para></entry>
<entry>
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure containing
the credentials that you want to use for authentication.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>servercredp</literal></para></entry>
<entry>
<para>Pointer to a pointer to an <olink targetptr="bdakg">berval</olink> structure
containing any credentials returned by the server. When done, you can free
this by calling the <olink targetptr="bdany">ber_alloc</olink> function.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garxf"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
was sent successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAPv3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request to send to the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when the LDAP API library was decoding the BER-encoded results received from
the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garwc"><title>Description</title>
<para>The <function>ldap_sasl_bind_s</function> function authenticates your
client to an LDAP server by using a specified SASL mechanism. It is a synchronous
function, which directly returns the results of the operation. If you want
to perform other operations while waiting for the results of this operation,
call the asynchronous function <olink targetptr="bdauw">ldap_sasl_bind</olink>.
After authenticating a client through SASL, an LDAP server can return a set
of credentials in the results. The <literal>servercredp</literal> argument
points to this value.</para></sect3>
<sect3 id="garxz"><title>See Also</title>
<para><olink targetptr="bdauw">ldap_sasl_bind</olink></para></sect3>
</sect2>
<sect2 id="bdauy"><title><function>ldap_search</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_search</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_search</function></primary>
</indexterm>
<para>The <function>ldap_search</function> function searches the directory
asynchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdauz">ldap_search_ext
</olink>  instead.</para></note>
<sect3 id="garxc"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_search( LDAP *ld, const char *base, int scope,
     const char* filter, char **attrs, int attrsonly );</programlisting>
</sect3>
<sect3 id="garxl"><title>Parameters</title>
<table frame="topbot" id="garxq"><title><function>ldap_search</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>DN of the entry that serves as the starting point for the search. For
example, setting base to <literal>dc=example,dc=com</literal> restricts the
search to entries at <literal>example.com</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope of the search, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
one level beneath the entry specified by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches the entry specified
by base and all entries at all levels beneath the entry specified by base.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>filter</literal></para></entry>
<entry>
<para>String representation of the filter to apply in the search. You can
specify simple filters with the following syntax:</para>
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
attributevalue</replaceable><literal>)</literal></para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of attribute types to return
from entries that match filter. If you specify a <literal>NULL</literal>,
all attributes will be returned.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garwe"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_search</function> operation.</para>
<note><para>To check the result of this operation, call  <olink targetptr="bdauu">
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
See <olink targetptr="bdava">ldap_search_ext_s</olink> for a list of possible
result codes.</para></note>
</sect3>
<sect3 id="garww"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdauz">ldap_search_ext
</olink> .</para></sect3>
<sect3 id="garwg"><title>Example</title>
<para><olink targetptr="ldap-search-example">Example 21&ndash;44</olink> searches
a directory.</para>
<example id="ldap-search-example"><title>Using <function>ldap_search</function></title>
<programlisting>#include "examples.h"

static void do_other_work();
unsigned long global_counter = 0;

int
main( int argc, char **argv )
{
  LDAP *ld;
  LDAPMessage *result, *e;
  BerElement *ber;
  char *a, *dn;
  char **vals;
  int i, rc, finished, msgid;
  int num_entries = 0;
  struct timeval zerotime;

  zerotime.tv_sec = zerotime.tv_usec = 0L;

/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_simple_bind_s" );
  return( 1 );
}
/* search for all entries with surname of Jensen */
if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
      MY_FILTER, NULL, 0 )) == -1 ) {
  ldap_perror( ld, "ldap_search" );
  return( 1 );
}

/* Loop, polling for results until finished */
finished = 0;
while ( !finished ) {
  /*
  * Poll for results.   We call ldap_result with the "all" parameter
  * set to zero. This causes ldap_result() to return exactly one
  * entry if at least one entry is available. This allows us to
  * display the entries as they are received.
  */
  result = NULL;
  rc = ldap_result( ld, msgid, 0, &amp;zerotime, &amp;result );
  switch ( rc ) {
  case -1:
    /* some error occurred */
    ldap_perror( ld, "ldap_result" );
    return( 1 );
  case 0:
  /* Timeout was exceeded. No entries are ready for retrieval. */
    if ( result != NULL ) {
      ldap_msgfree( result );
    }
    break;
  default:
  /*
  * Either an entry is ready for retrieval, or all entries have
  * been retrieved.
  */
    if (( e = ldap_first_entry( ld, result )) == NULL ) {
      /* All done */
      finished = 1;
      if ( result != NULL ) {
        ldap_msgfree( result );
      }
      continue;
      }
    /* for each entry print out name + all attrs and values */
    num_entries++;
    if (( dn = ldap_get_dn( ld, e )) != NULL ) {
      printf( "dn: %s\n", dn );
      ldap_memfree( dn );
    }
    for ( a = ldap_first_attribute( ld, e, &amp;ber );
     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
      if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
        for ( i = 0; vals[ i ] != NULL; i++ ) {
          printf( "%s: %s\n", a, vals[ i ] );
        }
      ldap_value_free( vals );
      }
      ldap_memfree( a );
    }
    if ( ber != NULL ) {
      ldap_ber_free( ber, 0 );
    }
    printf( "\n" );
    ldap_msgfree( result );
  }
  /* Do other work here while you are waiting... */
  do_other_work();
}

/* All done. Print a summary. */
printf( "%d entries retrieved. I counted to %ld "
      "while waiting.\n", num_entries, global_counter );
ldap_unbind( ld );
return( 0 );
}

/*
 * Perform other work while polling for results. */
static void
do_other_work()
{
    global_counter++;
}</programlisting>
</example>
</sect3>
<sect3 id="garxs"><title>See Also</title>
<para><olink targetptr="bdauz">ldap_search_ext</olink></para></sect3>
</sect2>
<sect2 id="bdauz"><title><function>ldap_search_ext</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_search_ext</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_search_ext</function></primary>
</indexterm>
<para>The <function>ldap_search_ext</function> function searches the directory
asynchronously.</para>
<note><para><function>ldap_search_ext</function> is a new version of the  <olink targetptr="bdauy">ldap_search</olink> function. If you are writing a new LDAP
client, you should call  <function>ldap_search_ext</function>.</para></note>
<sect3 id="garxb"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_search_ext( LDAP *ld, const char *base, int scope,
    const char *filter, char **attrs, int attrsonly,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     struct timeval *timeoutp, int sizelimit, int *msgidp );</programlisting>
</sect3>
<sect3 id="garwi"><title>Parameters</title>
<table frame="topbot" id="garwp"><title><function>ldap_search_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>DN of the entry that serves as the starting point for the search. For
example, setting base to <literal>dc=example,dc=com</literal> restricts the
search to entries at <literal>example.com</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope of the search, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
one level beneath the entry specified by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches the entry specified
by base and all entries at all levels beneath the entry specified by base.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>filter</literal></para></entry>
<entry>
<para>String representation of the filter to apply in the search. You can
specify simple filters with the following syntax:</para>
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
attributevalue</replaceable><literal>)</literal></para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of attribute types to return
from entries that match filter. If you specify a <literal>NULL</literal>,
all attributes will be returned.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>timeoutp</literal></para></entry>
<entry>
<para>Pointer to a <literal>timeval</literal> structure specifying the maximum
time to wait for the results of the search. Pass <literal>NULL</literal> to
use the default time limit for the current connection. To specify an infinite
time limit, set the  <literal>tv_sec</literal> and <literal>tv_usec</literal> fields
in the <literal>timeval</literal> structure to 0.</para></entry>
</row>
<row>
<entry>
<para><literal>sizelimit</literal></para></entry>
<entry>
<para>Maximum number of results to return in the search. Pass <literal>-1</literal> to
use the default size limit for the current connection.</para></entry>
</row>
<row>
<entry>
<para><literal>msgidp</literal></para></entry>
<entry>
<para>Pointer to an integer that will be set to the message ID of the LDAP
operation.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garyc"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
was sent successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request&mdash;for example, as a session preference&mdash;and
your LDAP client does not specify that it is using the LDAP v3. Make sure
that you set the version of your LDAP client to version 3 before calling this
function.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request to send to the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="garwx"><title>Description</title>
<para>The <function>ldap_search_ext</function> function searches the directory
for matching entries. <function>ldap_search_ext</function> is an asynchronous
function; it does not directly return results. If you want the results to
be returned directly by the function, call the synchronous function <olink targetptr="bdava">ldap_search_ext_s</olink> . You can also use this function
to pass LDAP server controls to the server if you want the server to sort
the results or if you want to request a persistent search. (See <olink targetptr="bdare">ldap_create_sort_control</olink> and <olink targetptr="bdara">ldap_create_persistentsearch_control
</olink> for more information.) In order to get the results of the <function>ldap_search_ext
</function> operation, you need to call the <olink targetptr="bdauu">ldap_result</olink> and
the <olink targetptr="bdaun">ldap_parse_result</olink> functions.</para></sect3>
<sect3 id="garya"><title>See Also</title>
<para><olink targetptr="bdava">ldap_search_ext_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
</olink></para></sect3>
</sect2>
<sect2 id="bdava"><title><function>ldap_search_ext_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_search_ext_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_search_ext_s</function></primary>
</indexterm>
<para>The <function>ldap_search_ext_s</function> function searches the directory
synchronously.</para>
<note><para><function>ldap_search_ext_s</function> is a new version of the <olink targetptr="bdavb">ldap_search_s</olink> function. If you are writing a new
LDAP client, you should call <function>ldap_search_ext_s</function>.</para>
</note>
<sect3 id="garxw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
     const char *filter, char **attrs, int attrsonly,
     LDAPControl **serverctrls, LDAPControl **clientctrls,
     struct timeval *timeoutp, int sizelimit, LDAPMessage **res );</programlisting>
</sect3>
<sect3 id="garyx"><title>Parameters</title>
<table frame="topbot" id="garyl"><title><function>ldap_search_ext_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>DN of the entry that serves as the starting point for the search. For
example, setting base to <literal>dc=example,dc=com</literal> restricts the
search to entries at <literal>example.com</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope of the search, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
one level beneath the entry specified by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
at all levels beneath the entry specified by base.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>filter</literal></para></entry>
<entry>
<para>String representation of the filter to apply in the search. You can
specify simple filters with the following syntax:</para>
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
attributevalue</replaceable><literal>)</literal></para></entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of attribute types to return
from entries that match filter. If you specify a <literal>NULL</literal>,
all attributes will be returned.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>timeoutp</literal></para></entry>
<entry>
<para>Pointer to a <literal>timeval</literal> structure specifying the maximum
time to wait for the results of the search.</para></entry>
</row>
<row>
<entry>
<para><literal>sizelimit</literal></para></entry>
<entry>
<para>Maximum number of results to return in the search.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Results of the search (when the call is completed).</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
was sent successfully.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request&mdash;for example, as a session preference&mdash;and
your LDAP client does not specify that it is using the LDAP v3. Make sure
that you set the version of your LDAP client to version 3 before calling this
function.</para></listitem>
<listitem><para><errorcode>LDAP_FILTER_ERROR</errorcode> if an error occurred
when parsing and BER-encoding the search filter specified by the filter argument.
</para></listitem>
<listitem><para><errorcode>LDAP_TIMEOUT</errorcode> if the search exceeded
the time specified by the <parameter>timeoutp</parameter> argument.</para>
</listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request to send to the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when the LDAP API library was decoding the BER-encoded results received from
the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="garyz"><title>Description</title>
<para>The <function>ldap_search_ext_s</function> searches the directory for
matching entries. The function <function>ldap_search_ext_s</function> is synchronous;
it directly returns the results of the operation. If you want to perform other
operations while waiting for the results of this operation, call the asynchronous
function  <olink targetptr="bdauz">ldap_search_ext</olink>. You can also use <function>
ldap_search_ext_s</function> to pass LDAP server controls to the server if
you want the server to sort the results or if you want to request a persistent
search. (See <olink targetptr="bdare">ldap_create_sort_control</olink>  and <olink targetptr="bdara">ldap_create_persistentsearch_control</olink> for more information.)
</para></sect3>
<sect3 id="garze"><title>See Also</title>
<para><olink targetptr="bdauz">ldap_search_ext</olink></para></sect3>
</sect2>
<sect2 id="bdavb"><title><function>ldap_search_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_search_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_search_s</function></primary>
</indexterm>
<para>The <function>ldap_search_s</function> function searches the directory
synchronously.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdava">ldap_search_ext_s
</olink>  instead.</para></note>
<sect3 id="garyr"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_search_s( LDAP *ld, const char *base, int scope,
     const char* filter, char **attrs, int attrsonly,
     LDAPMessage **res );</programlisting>
</sect3>
<sect3 id="garzs"><title>Parameters</title>
<para>This function has the parameters listed in <olink targetptr="bdavb">ldap_search_s
</olink> .</para>
<table frame="topbot" id="garzh"><title><function>ldap_search_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>DN of the entry that serves as the starting point for the search. For
example, setting base to <literal>dc=example,dc=com</literal> restricts the
search to entries at <literal>example.com</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope of the search, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
one level beneath the entry specified by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
at all levels beneath the entry specified by base.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>filter</literal></para></entry>
<entry>
<para>String representation of the filter to apply in the search. You can
specify simple filters with the following syntax:</para>
<programlisting>(attributetype=attributevalue)</programlisting>
</entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of attribute types to return
from entries that match filter. If you specify a <literal>NULL</literal>,
all attributes will be returned.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Results of the search (when the call is completed).</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzp"><title>Returns</title>
<para>For a list of possible result codes for an LDAP search operation, see <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
<sect3 id="garyt"><title>Description</title>
<para>Use the newer version of this function, <olink targetptr="bdava">ldap_search_ext_s
</olink> .</para></sect3>
<sect3 id="garyf"><title>Example</title>
<para><olink targetptr="ldap-search-s-example">Example 21&ndash;45</olink> searches
the directory for all people whose surname (last name) is <literal>Jensen</literal>.
</para>
<example id="ldap-search-s-example"><title>Using <function>ldap_search_s</function></title>
<programlisting>#include "examples.h"

int main( int argc, char **argv )
{
  LDAP *ld;
  LDAPMessage *result, *e;
  BerElement *ber;
  char *a, *dn;
  char **vals;
  int i;
  /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
  if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
    perror( "ldap_init" );
    return( 1 );
  }
  /* authenticate to the directory as nobody */
  if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_simple_bind_s" );
    return( 1 );
  }
  /* search for all entries with surname of Jensen */
  if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
    MY_FILTER, NULL, 0, &amp;result ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_search_s" );
    return( 1 );
  }
  /* for each entry print out name + all attrs and values */
  for ( e = ldap_first_entry( ld, result ); e != NULL;
   e = ldap_next_entry( ld, e ) ) {
    if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
      printf( "dn: %s\n", dn );
      ldap_memfree( dn );
    }
    for ( a = ldap_first_attribute( ld, e, &amp;ber );
     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
      if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
        for ( i = 0; vals[i] != NULL; i++ ) {
          printf( "%s: %s\n", a, vals[i] );
        }
        ldap_value_free( vals );
      }
      ldap_memfree( a );
    }
    if ( ber != NULL ) {
      ldap_ber_free( ber, 0 );
    }
    printf( "\n" );
  }
  ldap_msgfree( result );
  ldap_unbind( ld );
  return( 0 );
}</programlisting>
</example>
</sect3>
<sect3 id="garzt"><title>See Also</title>
<para><olink targetptr="bdava">ldap_search_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdavc"><title><function>ldap_search_st</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_search_st</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_search_st</function></primary>
</indexterm>
<para>The <function>ldap_search_st</function> function searches the directory
synchronously within a specified time limit.</para>
<note><para>This is an older function that is included in the SDK for backward-compatibility.
If you are writing a new LDAP client, use <olink targetptr="bdava">ldap_search_ext_s
</olink>  instead.</para></note>
<sect3 id="garzx"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_search_st( LDAP *ld, const char *base, int scope,
     const char* filter, char **attrs, int attrsonly,
     struct timeval *timeout, LDAPMessage **res );</programlisting>
</sect3>
<sect3 id="garzy"><title>Parameters</title>
<table frame="topbot" id="garyv"><title><function>ldap_search_st</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>base</literal></para></entry>
<entry>
<para>DN of the entry that serves as the starting point for the search. For
example, setting base to <literal>dc=example,dc=com</literal> restricts the
search to entries at <literal>example.com</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>scope</literal></para></entry>
<entry>
<para>Scope of the search, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
one level beneath the entry specified by base.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
at all levels beneath the entry specified by base.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>filter</literal></para></entry>
<entry>
<para>String representation of the filter to apply in the search. You can
specify simple filters with the following syntax:</para>
<programlisting>(attributetype=attributevalue)</programlisting>
</entry>
</row>
<row>
<entry>
<para><literal>attrs</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated array of attribute types to return
from entries that match filter. If you specify a <literal>NULL</literal>,
all attributes will be returned.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para>0 specifies that both attribute types and attribute values
are returned.</para></listitem>
<listitem><para>1 specifies that only attribute types are returned.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>timeout</literal></para></entry>
<entry>
<para>Maximum time to wait for the results of the search.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Results of the search (when the call is completed).</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzi"><title>Returns</title>
<para>For a list of possible result codes for an LDAP search operation, see <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
<sect3 id="garzc"><title>Description</title>
<para>Please use the newer version of this function, <olink targetptr="bdava">ldap_search_ext_s
</olink> .</para></sect3>
<sect3 id="gasae"><title>See Also</title>
<para><olink targetptr="bdava">ldap_search_ext_s</olink></para></sect3>
</sect2>
<sect2 id="bdavd"><title><function>ldap_set_filter_additions</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_set_filter_additions</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_set_filter_additions</function></primary>
</indexterm>
<para>The <function>ldap_set_filter_additions</function> function sets a prefix
to be prepended and a suffix to be appended to all filters returned by the
 <function>ldap_getfirstfilter</function> and <function>ldap_getnextfilter</function> function
calls.</para>
<sect3 id="garzv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
     char *suffix );</programlisting>
</sect3>
<sect3 id="garym"><title>Parameters</title>
<table frame="topbot" id="garyp"><title><function>ldap_set_filter_additions</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lfdp</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
</entry>
</row>
<row>
<entry>
<para><literal>prefix</literal></para></entry>
<entry>
<para>Prefix to prepend to all filters. If <literal>NULL</literal>, no prefix
is prepended.</para></entry>
</row>
<row>
<entry>
<para><literal>suffix</literal></para></entry>
<entry>
<para>Suffix to append to all filters. If <literal>NULL</literal>, no suffix
is appended.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzq"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garye"><title>Example</title>
<para><olink targetptr="ldap-set-filter-additions-example">Example 21&ndash;46</olink> loads
the filter configuration file named <literal>myfilters.conf</literal>  into
memory and adds the prefix <literal>"(&amp;(objectClass=person)"</literal> and
the suffix <literal>")"</literal> to each filter retrieved.</para>
<example id="ldap-set-filter-additions-example"><title>Using <function>ldap_set_filter_additions
</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
char *prefix = "(&amp;(objectClass=person)";
char *suffix = ")";
int rc;
...
lfdp = ldap_init_getfilter( filter_file );
rc = ldap_set_filter_additions( ldfp, prefix, suffix );
if ( rc != LDAP_SUCCESS ) {
  printf( "Error setting filter prefix and suffix\n");
  return( rc );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garyk"><title>See Also</title>
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink>,  <olink targetptr="bdasr">ldap_getnextfilter</olink></para></sect3>
</sect2>
<sect2 id="bdave"><title><function>ldap_setfilteraffixes</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_setfilteraffixes</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_setfilteraffixes</function></primary>
</indexterm>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavd">ldap_set_filter_additions</olink> instead.</para></note>
<sect3 id="garzd"><title>See Also</title>
<para><olink targetptr="bdavd">ldap_set_filter_additions</olink></para></sect3>
</sect2>
<sect2 id="bdavf"><title><function>ldap_set_lderrno</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_set_lderrno</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_set_lderrno</function></primary>
</indexterm>
<para>The <function>ldap_set_lderrno</function> function sets an error code
and information about an error in an <olink targetptr="bdakj">LDAP</olink> structure.
</para>
<sect3 id="garzu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );</programlisting>
</sect3>
<sect3 id="garzk"><title>Parameters</title>
<table frame="topbot" id="garyn"><title><function>ldap_set_lderrno</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>e</literal></para></entry>
<entry>
<para>The error code that you want to set.</para></entry>
</row>
<row>
<entry>
<para><literal>m</literal></para></entry>
<entry>
<para>In the event that an entry for a specified DN cannot be found, set this
parameter to the portion of the DN that identifies an existing entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>The text of the error message that you want associated with this error
code.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzf"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garyj"><title>Description</title>
<para>The <function>ldap_set_lderrno</function> function sets an error code
and information about an error in an <olink targetptr="bdakj">LDAP</olink> structure.
You can call this function to set error information that will be retrieved
by subsequent <olink targetptr="bdasq">ldap_get_lderrno</olink> function calls.</para>
</sect3>
<sect3 id="garzw"><title>Example</title>
<para><olink targetptr="ldap-set-lderrno-example">Example 21&ndash;47</olink> attempts
to perform an operation. If the operation fails, the <errorcode>LDAP_PARAM_ERROR</errorcode> error
code is placed in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
<example id="ldap-set-lderrno-example"><title>Using <function>ldap_set_lderrno</function></title>
<programlisting>#include &lt;ldap.h>
int rc;
char *errmsg = "Invalid parameter";
...
if ( ldap_my_function() != LDAP_SUCCESS ) {
  rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg );
  if ( rc != LDAP_SUCCESS ) {
    printf( "Error: %d\nError code could not be set.\n", rc );
  }
  return( rc );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garys"><title>See Also</title>
<para><olink targetptr="bdarq">ldap_err2string</olink>,  <olink targetptr="bdaur">
ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error</olink></para>
</sect3>
</sect2>
<sect2 id="bdavg"><title><function>ldap_set_option</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_set_option</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_set_option</function></primary>
</indexterm>
<para>The function <function>ldap_set_option</function> sets session preferences
in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
<sect3 id="garyy"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_set_option( LDAP *ld, int option, const void *optdata );</programlisting>
</sect3>
<sect3 id="garyw"><title>Parameters</title>
<table frame="topbot" id="garyh"><title><function>ldap_set_option</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server. If NULL, you are setting
the default options that will apply to any new LDAP connection handles that
are subsequently created.</para></entry>
</row>
<row>
<entry>
<para><literal>option</literal></para></entry>
<entry>
<para>Option that you want to set. See <olink targetptr="ldap-set-option-options">
Table 21&ndash;182</olink> for available options of this parameter.</para>
</entry>
</row>
<row>
<entry>
<para><literal>optdata</literal></para></entry>
<entry>
<para>Pointer to the value of the option that you want to set. Available data
types are also listed in <olink targetptr="ldap-set-option-options">Table
21&ndash;182</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>The <literal>option</literal> parameter can have one of the values listed
in <olink targetptr="ldap-set-option-options">Table 21&ndash;182</olink>.</para>
<table frame="topbot" id="ldap-set-option-options"><title>Options for <function>ldap_set_option
</function></title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Option</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>LDAP_OPT_API_FEATURE_INFO</literal></para></entry>
<entry>
<para>Retrieves information about the revision of a supported LDAP feature.
This option is READ-ONLY and cannot be set.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIFeatureInfo
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_API_INFO</literal></para></entry>
<entry>
<para>Retrieves information about the API implementation at execution time
(API version, protocol version, the names of supported API extensions with
their vendor name version, etc.). For details on the structure returned, refer
to the <literal>ldap.h</literal> header file. This option is READ-ONLY and
cannot be set.</para>
<para>The data type for the <literal>optdata</literal> parameter is  <literal>(LDAPAPIInfo
 *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_CLIENT_CONTROLS</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing the LDAP v3 client controls you want sent with every request
by default.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
***)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DESC</literal></para></entry>
<entry>
<para>Socket descriptor underlying the main LDAP connection. The <literal>LBER_SOCKET
</literal>  data type depends on the platform that you are using:</para>
<itemizedlist>
<listitem><para><literal>int</literal> in UNIX.</para></listitem>
<listitem><para><literal>SOCKET</literal> in Windows.</para><para>The data
type for the <literal>optdata</literal>  parameter is <literal>(LBER_SOCKET
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DEREF</literal></para></entry>
<entry>
<para>Determines how aliases work during a search. <literal>optdata</literal> can
be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_DEREF_NEVER</literal> specifies that aliases
are never dereferenced.</para></listitem>
<listitem><para><literal>LDAP_DEREF_SEARCHING</literal> specifies that aliases
are dereferenced when searching under the base object (but not when finding
the base object).</para></listitem>
<listitem><para><literal>LDAP_DEREF_FINDING</literal> specifies that aliases
are dereferenced when finding the base object (but not when searching under
the base object).</para></listitem>
<listitem><para><literal>LDAP_DEREF_ALWAYS</literal> specifies that aliases
are always dereferenced when finding and searching under the base object.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_DNS_FN_PTRS</literal></para></entry>
<entry>
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
DNS functions for getting the host entry of the LDAP server.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_dns_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_ERROR_NUMBER</literal></para></entry>
<entry>
<para>Retrieves the result code for the most recent LDAP error that occurred
in this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_ERROR_STRING</literal></para></entry>
<entry>
<para>Retrieves the error message returned with the result code for the most
recent LDAP error that occurred in this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_EXTRA_THREAD_FN_PTRS</literal></para></entry>
<entry>
<para>Lets you specify the locking and semaphore functions that you want called
when getting results from the server.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_extra_thread_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_HOST_NAME</literal></para></entry>
<entry>
<para>Sets the host name (or list of hosts) for the primary LDAP server.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_IO_FN_PTRS</literal></para></entry>
<entry>
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
communication stacks.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_io_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_MATCHED_DN</literal></para></entry>
<entry>
<para>Gets the matched DN value returned with the most recent LDAP error that
occurred for this session.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
**)</literal></para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_MEMALLOC_FN_PTRS</literal></para></entry>
<entry>
<para>Gets a pointer to the callback structure which you previously set.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_memalloc_fnsldap_io_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_PROTOCOL_VERSION</literal></para></entry>
<entry>
<para>Version of the protocol supported by your client. You can specify either <literal>
LDAP_VERSION2</literal> or <literal>LDAP_VERSION3</literal>. If no version
is set, the default is <literal>LDAP_VERSION2</literal>. In order to use LDAP
v3 features, you need to set the protocol version to <literal>LDAP_VERSION3</literal>.
</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REBIND_ARG</literal></para></entry>
<entry>
<para>Lets you set the last argument passed to the routine specified by <literal>
LDAP_OPT_REBIND_FN</literal>. You can also set this option by calling the <olink targetptr="bdavh">ldap_set_rebind_proc</olink>  function.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(void
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REBIND_FN</literal></para></entry>
<entry>
<para>Lets you set the routine to be called when you need to authenticate
a connection with another LDAP server (for example, during the course of following
a referral). You can also set this option by calling the <olink targetptr="bdavh">
ldap_set_rebind_proc</olink>  function.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAP_REBINDPROC_CALLBACK
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_RECONNECT</literal></para></entry>
<entry>
<para>If the connection to the server is lost, determines whether or not the
same connection handle should be used to reconnect to the server. By default,
this option is off. To handle failover use following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the same connection
handle can be used to reconnect to the server.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that you want to
create a new connection handle to connect to the server.</para><para>The data
type for the  <literal>optdata</literal> parameter is <literal>(int *)</literal>.
</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REFERRALS</literal></para></entry>
<entry>
<para>Determines whether or not the client should follow referrals. By default,
the client follows referrals. <literal>optdata</literal> can be one of the
following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the server should
follow referrals.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that the server
should not follow referrals.</para><para>The data type for the <literal>optdata</literal> parameter
is <literal>(int *)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_REFERRAL_HOP_LIMIT</literal></para></entry>
<entry>
<para>Maximum number of referrals the client should follow in a sequence.
In other words, the client can only be referred this number of times before
it gives up. By default, the maximum number of referrals that the client can
follow in a sequence is 5 for the initial connection. This limit does not
apply to individual requests that generate multiple referrals in parallel.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_RESTART</literal></para></entry>
<entry>
<para>Determines whether or not LDAP I/O operations should be restarted automatically
if they are prematurely aborted. <literal>optdata</literal> can be one of
the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that I/O operations
should be restarted automatically.</para></listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that I/O operations
should not be restarted automatically.</para><para>The data type for the <literal>
optdata</literal>  parameter is <literal>(int *)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SERVER_CONTROLS</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing the LDAP v3 server controls you want sent with every request
by default. Typically, since controls are specific to the type of request,
you may want to pass the controls using operation-specific functions (such
as  <olink targetptr="bdaqa">ldap_add_ext</olink>) instead.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
***)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SIZELIMIT</literal></para></entry>
<entry>
<para>Maximum number of entries that should be returned by the server in search
results. The LDAP server may impose a smaller size limit than the limit you
specify as the server administrator also has the ability to set this limit.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_SSL</literal></para></entry>
<entry>
<para>Determines whether or not SSL is enabled. <literal>optdata</literal> can
be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that SSL is enabled.</para>
</listitem>
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that SSL is disabled.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_THREAD_FN_PTRS</literal></para></entry>
<entry>
<para>Lets you specify the thread function pointers. </para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
ldap_thread_fns *)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_OPT_TIMELIMIT</literal></para></entry>
<entry>
<para>Maximum number of seconds that should be spent by the server when answering
a search request. The LDAP server may impose a shorter time limit than the
limit you specify as the server administrator also has the ability to set
this limit.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_EXTIO_FN_PTRS</literal></para></entry>
<entry>
<para>Extended I/O function callback option.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_CONNECT_TIMEOUT</literal></para></entry>
<entry>
<para>Value of a time out (expressed in milliseconds) for non-blocking connect
call.</para>
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>LDAP_X_OPT_SOCKBUF</literal></para></entry>
<entry>
<para>Socket buffer structure associated to the LDAP connection.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>See also <citerefentry><refentrytitle>ldap_set_option</refentrytitle>
<manvolnum>3LDAP</manvolnum></citerefentry> for details on <literal>LDAP_OPT_X_SASL*
</literal> parameters.</para></sect3>
<sect3 id="garyu"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="garzz"><title>Example</title>
<example id="garza"><title>Using <function>ldap_set_option</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
int max_ret = 100, max_tim = 30;
char *host = "ldap.sun.com";
...
/* Initialize a session with the LDAP server ldap.sun.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}

/* Set the maximum number of entries returned */
if ( ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &amp;max_ret) !
     LDAP_SUCCESS) {
  ldap_perror( ld, "ldap_set_option" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="garyg"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdass">ldap_get_option</olink></para></sect3>
</sect2>
<sect2 id="bdavh"><title><function>ldap_set_rebind_proc</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_set_rebind_proc</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_set_rebind_proc</function></primary>
</indexterm>
<para>The <function>ldap_set_rebind_proc</function> function sets a <emphasis>rebind
</emphasis> , which is called by your client to obtain authentication credentials
when following a referral.</para>
<sect3 id="gasad"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
void ldap_set_rebind_proc( LDAP *ld,
    LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );</programlisting>
</sect3>
<sect3 id="gasab"><title>Parameters</title>
<table frame="topbot" id="garzb"><title><function>ldap_set_rebind_proc</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>rebindproc</literal></para></entry>
<entry>
<para>Pointer to a function called back to obtain bind credentials when a
new server is contacted during an LDAP referral.</para></entry>
</row>
<row>
<entry>
<para><literal>arg</literal></para></entry>
<entry>
<para>Pointer to an additional argument that you want to pass to the rebind
function.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzn"><title>Description</title>
<para>Call <function>ldap_set_rebind_proc</function> to specify the rebind
function. This rebind function is called by the LDAP client when following
a referral to a new LDAP server. It is responsible for obtaining the credentials
used to authenticate to the new server. For example, suppose LDAP server A
sends a referral to your client. The referral points your client to LDAP server
B. When automatically following the referral, your client calls the rebind
function to obtain a DN and credentials; your client uses these to authenticate
to server B. By default, if you do not call  <function>ldap_set_rebind_proc</function> or
if you pass <literal>NULL</literal> for the  <literal>rebindproc</literal> argument,
your client authenticates anonymously when following referrals.</para>
<para>The rebind function that you specify with <function>ldap_set_rebind_proc</function> should
have the following prototype:</para>
<programlisting>int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp,
     char **passwdp, int *authmethodp, int freeit, void *arg );</programlisting>
<note><para><literal>LDAP_CALL</literal> and <literal>LDAP_CALLBACK</literal> are
used to set up calling conventions, such as Pascal calling conventions on
Windows. These are defined in the <literal>lber.h</literal> header file.</para>
</note>
<para>The following procedure explains what the rebind function is expected
to do. LDAP clients that are built with &DirectorySDKForC; use this procedure
when following referrals.</para>
<task id="garyi"><title>To Follow Referrals</title>
<procedure>
<step><para>The LDAP server sends a referral back to the client.</para></step>
<step><para>The client calls the rebind function, passing                
       <literal>0</literal> as the                       <literal>freeit</literal> argument.
</para></step>
<step><para>The rebind function sets the                       <literal>dnp</literal>,
                      <literal>passwdp</literal>, and                    
   <literal>authmethodp</literal> arguments to point to the following information:
</para>
<itemizedlist>
<listitem><para>The <literal>dnp</literal> argument is set to point to the
DN to be used to authenticate to the new LDAP server.</para>
<itemizedlist>
<listitem><para>The <literal>passwdp</literal> argument is set to point to
the credentials for this DN.</para></listitem>
<listitem><para>The <literal>authmethodp</literal> argument is set to point
to the method of authentication used (for example, <literal>LDAP_AUTH_SIMPLE</literal>).
</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</step>
<step><para>If successful, the rebind function returns                   
                         <errorcode>LDAP_SUCCESS</errorcode>             
        , and referral processing continues. (If any other value is returned,
referral processing stops, and that value is returned as the result code for
the original LDAP request.)</para></step>
<step><para>The client gets the DN, credentials, and authentication method
from the arguments of the rebind function and uses this information to authenticate
to the new LDAP server.</para></step>
<step><para>The client calls the rebind function again, passing          
            <literal>1</literal> as the                       <literal>freeit</literal> argument.
</para></step>
<step><para>The rebind function frees any memory allocated earlier to specify
the DN and credentials.</para><para>You need to write a rebind function that
does the following:</para>
<itemizedlist>
<listitem><para>If <literal>freeit</literal> is <literal>0</literal>, set
the following pointers:</para>
<itemizedlist>
<listitem><para>Set <literal>dnp</literal> to point to the DN to be used for
authentication.</para></listitem>
<listitem><para>Set <literal>passwdp</literal> to point to the credentials
to be used for authentication.</para></listitem>
<listitem><para>Set <literal>authmethodp</literal> to point to the method
of authentication used (for example, <literal>LDAP_AUTH_SIMPLE</literal>).</para>
<para>You can also make use of the <literal>arg</literal> argument, which
is a pointer to the argument specified in the <function>ldap_set_rebind_proc</function> function.
If successful, returns <errorcode>LDAP_SUCCESS</errorcode>. Otherwise, returns
the appropriate LDAP error code.</para></listitem>
</itemizedlist>
<para>If <literal>freeit</literal> is <literal>1</literal>, free any memory
that you allocated to create the DN and credentials.</para><para>After you
have defined this function, pass the function name to <function>ldap_set_rebind_proc
</function> to register your rebind function.</para></listitem>
</itemizedlist>
<note><para>In order to use the rebind function, the <literal>LDAP_OPT_REFERRALS</literal> option
must be set to <literal>LDAP_OPT_ON</literal>, so that your client automatically
follows referrals. This option is set to <literal>LDAP_OPT_ON</literal> by
default.</para></note>
</step>
</procedure>
</task>
</sect3>
<sect3 id="garzl"><title>Example</title>
<para><olink targetptr="ldap-set-rebind-proc-example">Example 21&ndash;49</olink> 
demonstrates how to write and register a rebind function.</para>
<example id="ldap-set-rebind-proc-example"><title>Using <function>ldap_set_rebind_proc
</function></title>
<programlisting>#include "ldap.h"
...
/* Declare your rebind function */
int rebindproc( LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg );
...
int main( int argc, char **argv )
{
  LDAP *ld;
  /* Additional argument to be passed to the rebind function */
  char *testarg = "cn=admin,cn=Administrators,cn=config";
  /* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
  if ( (ld = ldap_init( "directory.example.com", 389 )) == NULL ) {
    perror( "ldap_init" );
    return( 1 );
  }
  /* Specify the function used for reauthentication on referrals */
  ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );
  /* Authenticate */
  if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,dc=example,dc=com",
      "hifalutin" ) != LDAP_SUCCESS ) {
    ldap_perror( ld, "ldap_simple_bind_s" );
    return( 1 );
  }
  ...
  /* Your code to interact with the LDAP server */
  ...
}
...
/* rebindproc is the rebind function responsible for providing the DN,
  credentials, and authentication method used for authenticating the
  client to other Directory Servers.
  The function should set the following arguments:
  - dnp should point to the DN that will be used for authentication.
  - passwdp should point to the credentials used for authentication.
  - authmethodp should point to the method of authentication to be used
  (for example, LDAP_AUTH_SIMPLE).
  The function should return LDAP_SUCCESS if successful or an LDAP
  error code if an error occurs.
  In order to demonstrate how the freeit argument works, this example
  uses strdup() to copy the DN and password.  You can also just copy
  string pointers if the DN and password are already available as
  global variables.
*/
int LDAP_CALL LDAP_CALLBACK rebindproc(
  LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg )
{
  printf( "Rebind function called.\n" );
  switch ( freeit ) {
  /* Your client calls the rebind function with freeit==1 when it needs
    to free any memory you've allocated. */
  case 1:
    printf( "\tFreeing memory.\n" );
    if ( dnp &amp;&amp; *dnp ) {
      free( *dnp );
    }
    if ( passwdp &amp;&amp; *passwdp ) {
      free( *passwdp );
    }
    break;
  /* Your client calls the rebind function with freeit==0 when it needs
  to get the DN, credentials, and authentication method. */
  case 0:
    printf( "\tGetting DN and credentials.\n" );
    *dnp = strdup( "uid=username,o=OtherServerSuffix" );
    *passwdp = strdup( "23skidoo" );
    *authmethodp = LDAP_AUTH_SIMPLE;
    break;
  default:
    printf( "\tUnknown value of freeit argument: %d\n", freeit );
    break;
  }
  /* If you successfully set the DN and credentials, you should return
    LDAP_SUCCESS.  (Any other return code will stop the client from
    automatically following the referral. */
  return LDAP_SUCCESS;
}</programlisting>
</example>
</sect3>
<sect3 id="garyo"><title>See Also</title>
<para><olink targetptr="bdavi">ldap_simple_bind</olink>,  <olink targetptr="bdavj">ldap_simple_bind_s</olink></para></sect3>
</sect2>
<sect2 id="bdavi"><title><function>ldap_simple_bind</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_simple_bind</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_simple_bind</function></primary>
</indexterm>
<para>The <function>ldap_simple_bind</function> function synchronously authenticates
your client to the LDAP server using a DN and a password.</para>
<sect3 id="gasac"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd);</programlisting>
</sect3>
<sect3 id="garzr"><title>Parameters</title>
<table frame="topbot" id="garzj"><title><function>ldap_simple_bind</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>who</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
</para></entry>
</row>
<row>
<entry>
<para><literal>passwd</literal></para></entry>
<entry>
<para>Password of the user who wants to authenticate. For anonymous authentication,
set this or the who argument to <literal>NULL</literal>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="garzg"><title>Returns</title>
<para>Returns the message ID of the <function>ldap_simple_bind</function> operation.
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> 
and <olink targetptr="bdauv">ldap_result2error</olink>.</para></sect3>
<sect3 id="garyq"><title>Description</title>
<para>The <function>ldap_simple_bind</function> function authenticates to
the LDAP server. It verifies that the password supplied for authentication
matches the  <literal>userPassword</literal> attribute of the given entry. <function>
ldap_simple_bind</function> is an asynchronous function; it does not directly
return results. If you want the results to be returned directly by the function,
call the synchronous function  <olink targetptr="bdavj">ldap_simple_bind_s</olink>.
</para>
<note><para>If you specify a DN but no password, your client will bind to
the server anonymously. If you want a <literal>NULL</literal> password to
be rejected as an incorrect password, you need to write code to perform the
check before you call the  <function>ldap_simple_bind</function> function.</para>
<para>The use of this function may be a security threat if used on a non-secured
connection as the password is transmitted in clear text. For password-based
authentication, use a secure connection (<olink targetptr="bdavs">ldapssl_init</olink> or <olink targetptr="bdavx">ldapssl_tls_start_s</olink>) or SASL Digest-MD5 mechanism
(<olink targetptr="bdauw">ldap_sasl_bind</olink> or <olink targetptr="bdaux">ldap_sasl_bind_s
</olink>).</para></note>
</sect3>
<sect3 id="gasaa"><title>Example</title>
<para><olink targetptr="ldap-simple-bind-example">Example 21&ndash;50</olink> calls
 <function>ldap_simple_bind</function> to authenticate the user <literal>Barbara
Jensen</literal> to the directory.</para>
<example id="ldap-simple-bind-example"><title>Using <function>ldap_simple_bind</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
char *host = "ldap.sun.com";
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
char *pw = "hifalutin";
struct timeval zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Initialize a session with the LDAP server ldap.example.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Attempt to bind with the LDAP server */
msgid = ldap_simple_bind( ld, dn, pw );

/* Initialize the value returned by ldap_result() */
rc = 0;

/* While the operation is still running, do this: */
while ( rc == 0 ) {
  ... /* do other work while waiting */...

  /* Check the status of the LDAP operation */
  rc = ldap_result( ld, msgid, NULL, &amp;zerotime, &amp;result );
  switch( rc ) {
    /* If -1 was returned, an error occurred */
    case -1:
      ldap_perror( ld, "Error in results: " );
      return( 1 );
    /* If 0 was returned, the operation is still in progress */
    case 0:
      continue;
    /* If any other value is returned, assume we are done */
    default:
      /* Check if the "bind" operation was successful */
      if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
        ldap_perror( ld, "Error binding to server: " );
        return( 1 );
        }
  }
}
...</programlisting>
</example>
</sect3>
<sect3 id="garzo"><title>See Also</title>
<para><olink targetptr="bdavj">ldap_simple_bind_s</olink></para></sect3>
</sect2>
<sect2 id="bdavj"><title><function>ldap_simple_bind_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_simple_bind_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_simple_bind_s</function></primary>
</indexterm>
<para>The <function>ldap_simple_bind</function> function synchronously authenticates
your client to the LDAP server using a DN and a password.</para>
<sect3 id="gasar"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd );</programlisting>
</sect3>
<sect3 id="gasax"><title>Parameters</title>
<table frame="topbot" id="gasbi"><title><function>ldap_simple_bind_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>who</literal></para></entry>
<entry>
<para>DN of the user who wants to authenticate. For anonymous authentication,
set this or the <literal>passwd</literal> argument to <literal>NULL</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>passwd</literal></para></entry>
<entry>
<para>Password of the user who wants to authenticate. For anonymous authentication,
set this or the who argument to <literal>NULL</literal>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasah"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
was passed to the function.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request to send to the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when the LDAP API library was decoding the BER-encoded results received from
the server.</para></listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="gascd"><title>Description</title>
<para>The <function>ldap_simple_bind_s</function> function authenticates to
the LDAP server. It verifies that the password supplied for authentication
matches the  <literal>userPassword</literal> attribute of the given entry. <function>
ldap_simple_bind_s</function>  is a synchronous function, which directly returns
the results of the operation. If you want to perform other operations while
waiting for the results of this operation, call the asynchronous function <olink targetptr="bdavi">ldap_simple_bind</olink> instead.</para>
<note><para>If you specify a DN but no password, your client will bind to
the server anonymously. If you want a <literal>NULL</literal> password to
be rejected as an incorrect password, you need to write code to perform the
check before you call the  <function>ldap_simple_bind_s</function> function.</para>
<para>The use of this function may be a security threat if used on a non-secured
connection as the password is transmitted in clear text. For password-based
authentication, use a secure connection (<olink targetptr="bdavs">ldapssl_init</olink> or <olink targetptr="bdavx">ldapssl_tls_start_s</olink>) or SASL Digest-MD5 mechanism
(<olink targetptr="bdauw">ldap_sasl_bind</olink> or <olink targetptr="bdaux">ldap_sasl_bind_s
</olink>).</para></note>
</sect3>
<sect3 id="gasak"><title>Example</title>
<para><olink targetptr="ldap-simple-bind-s-example">Example 21&ndash;51</olink> 
uses the synchronous <function>ldap_simple_bind_s</function> function to authenticate
to the directory as the user <literal>Barbara Jensen</literal>.</para>
<example id="ldap-simple-bind-s-example"><title>Using <function>ldap_simple_bind_s
</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
char *host = "ldap.sun.com";
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
char *pw = "hifalutin";
...
/* Initialize a session with the LDAP server ldap.sun.com:389 */
/* Use prldap_init() for IPv6 support. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* Attempt to bind with the LDAP server */
if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Authentication failed: " );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasap"><title>See Also</title>
<para><olink targetptr="bdavi">ldap_simple_bind</olink></para></sect3>
</sect2>
<sect2 id="bdavk"><title><function>ldap_sort_entries</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_sort_entries</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_sort_entries</function></primary>
</indexterm>
<para>The <function>ldap_sort_entries</function> function sorts a chain of
entries retrieved from an LDAP search call.</para>
<sect3 id="gasaq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr,
    LDAP_CMP_CALLBACK *cmp );</programlisting>
</sect3>
<sect3 id="gascc"><title>Parameters</title>
<table frame="topbot" id="gasay"><title><function>ldap_sort_entries</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>chain</literal></para></entry>
<entry>
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
</row>
<row>
<entry>
<para><literal>attr</literal></para></entry>
<entry>
<para>Attribute to use when sorting the results. To sort by DN instead of
by attribute, use <literal>NULL</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>cmp</literal></para></entry>
<entry>
<para>Comparison function used when sorting the values.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasbe"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
To get the error code, call <olink targetptr="bdasq">ldap_get_lderrno</olink>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gasaf"><title>Description</title>
<para>The <function>ldap_sort_entries</function> function sorts a chain of
entries retrieved from an LDAP search call (<olink targetptr="bdavb">ldap_search_s
</olink> or <olink targetptr="bdauu">ldap_result</olink>) either by DN or
a specified attribute in the entries.</para></sect3>
<sect3 id="gasbj"><title>Example</title>
<para><olink targetptr="ldap-sort-entries-example">Example 21&ndash;52</olink> 
sorts entries by the <literal>roomNumber</literal> attribute.</para>
<example id="ldap-sort-entries-example"><title>Using <function>ldap_sort_entries</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;string.h>
#include &lt;ldap.h>
LDAP *ld;
LDAPMessage *result;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
char *sortby = "roomNumber";
...
/* Search the directory */
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
                    NULL, 0, &amp;result ) !=
     LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_search_s" );
  return( 1 );
}
/* Sort the results by room number, using strcasecmp */
if ( ldap_sort_entries( ld, &amp;result, sortby, strcasecmp ) !=
     LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_sort_entries" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasba"><title>See Also</title>
<para><olink targetptr="bdaty">ldap_multisort_entries</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s</olink>,
 <olink targetptr="bdakz">LDAP_CMP_CALLBACK</olink></para></sect3>
</sect2>
<sect2 id="ldap-start-tls-s"><title><function>ldap_start_tls_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_start_tls_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_start_tls_s</function></primary>
</indexterm>
<para>The <function>ldap_start_tls_s</function> initiates a Start Transport
Layer Security (TLS) operation as defined in <ulink
url="http://www.ietf.org/rfc/rfc4513.txt" type="text_url">RFC 4513</ulink>.</para>
<para>Before using this function, call <olink targetptr="bdavo">ldapssl_client_init
</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, or <olink targetptr="bdavn">ldapssl_advclientauth_init</olink> to initialize use of
the certificate database.</para>
<sect3><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
    LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgtl"><title><function>ldap_start_tls_s</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>List of LDAP server controls.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>List of client controls.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_OPERATIONS_ERROR</errorcode> if TLS has already
been established.</para></listitem>
<listitem><para><errorcode>LDAP_PROTOCOL_ERROR</errorcode> if TLS is not supported.
</para></listitem>
<listitem><para><errorcode>LDAP_REFERRAL</errorcode> if this server does not
support TLS, but the server referred to may.</para></listitem>
<listitem><para><errorcode>LDAP_UNAVAILABLE</errorcode> if the server is shutting
down, or supports TLS but cannot provide it at this time.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdavl"><title><function>ldap_sort_strcasecmp</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_sort_strcasecmp</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_sort_strcasecmp</function></primary>
</indexterm>
<para>The <function>ldap_sort_strcasecmp</function> routine compares two strings
and ignores any differences in case when comparing uppercase and lowercase
characters.</para>
<sect3 id="gasbc"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_sort_strcasecmp( const char **a, const char **b );</programlisting>
</sect3>
<sect3 id="gasbz"><title>Parameters</title>
<table frame="topbot" id="gasbu"><title><function>ldap_sort_strcasecmp</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>a</literal></para></entry>
<entry>
<para>Pointer to first string to compare</para></entry>
</row>
<row>
<entry>
<para><literal>b</literal></para></entry>
<entry>
<para>Pointer to second string to compare</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasbp"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If <literal>a</literal> is greater than <literal>b</literal>,
returns a value greater than <literal>0</literal>.</para></listitem>
<listitem><para>If <literal>a</literal> is equal to <literal>b</literal>,
returns  <literal>0</literal>.</para></listitem>
<listitem><para>If <literal>a</literal> is less than <literal>b</literal>,
returns a value less than <literal>0</literal>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasaj"><title>Description</title>
<para>The <function>ldap_sort_strcasecmp</function> routine compares two strings
and ignores any differences in case when comparing uppercase and lowercase
characters. This function is similar to the C function <function>strcasecmp</function>.
When sorting attribute values with <olink targetptr="bdavl">ldap_sort_strcasecmp</olink>,
call  <function>ldap_sort_strcasecmp</function> to compare the attribute values.</para>
<note><para>This function works with ASCII values only. For UTF-8 data, the
comparison result is unspecified.</para></note>
</sect3>
<sect3 id="gasau"><title>See Also</title>
<para><olink targetptr="bdavl">ldap_sort_strcasecmp</olink>,  <olink targetptr="bdamt">LDAP_VALCMP_CALLBACK</olink></para></sect3>
</sect2>
<sect2 id="bdavm"><title><function>ldap_sort_values</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_sort_values</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_sort_values</function></primary>
</indexterm>
<para>The <function>ldap_sort_values</function> function sorts an array of
values retrieved from an <olink targetptr="bdast">ldap_get_values</olink> call.</para>
<sect3 id="gasas"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_sort_values( LDAP *ld, char **vals,
     LDAP_VALCMP_CALLBACK cmp );</programlisting>
</sect3>
<sect3 id="gasca"><title>Parameters</title>
<table frame="topbot" id="gasbf"><title><function>ldap_sort_values</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>vals</literal></para></entry>
<entry>
<para>The array of values to sort.</para></entry>
</row>
<row>
<entry>
<para><literal>cmp</literal></para></entry>
<entry>
<para>Comparison function used when sorting the values. In the  <olink targetptr="bdavl">ldap_sort_strcasecmp</olink> function, the comparison function
must pass <literal>char **</literal> parameters. Because of this, you need
to use the <olink targetptr="bdavl">ldap_sort_strcasecmp</olink>  function,
rather than a function like <function>strcasecmp</function>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasby"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gascf"><title>Example</title>
<para><olink targetptr="ldap-sort-values-example">Example 21&ndash;53</olink> sorts
the values of attributes before printing them.</para>
<example id="ldap-sort-values-example"><title>Using <function>ldap_sort_values</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;string.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
char *my_searchbase = "dc=example,dc=com";
char *my_filter = "(sn=Jensen)";
...
    if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
      /* Sort the values of the attribute */
      if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) {
        ldap_perror( ld, "ldap_sort_values" );
        return( 1 );
      }
      /* Print the values of the attribute */
      for ( i = 0; vals[i] != NULL; i++ ) {
        printf( "%s: %s\n", a, vals[i] );
      }
      /* Free the values from memory */
      ldap_value_free( vals );
    }
...</programlisting>
</example>
</sect3>
<sect3 id="gasaz"><title>See Also</title>
<para><olink targetptr="bdast">ldap_get_values</olink>,  <olink targetptr="bdavl">
ldap_sort_strcasecmp</olink>, <olink targetptr="bdamt">LDAP_VALCMP_CALLBACK</olink>.
</para></sect3>
</sect2>
<sect2 id="bdavn"><title><function>ldapssl_advclientauth_init</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_ldapssl_*</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_ldapssl_*</function></primary>
</indexterm>
<para>The <function>ldapssl_advclientauth_init</function> function initialize
the secure parts (Security and SSL) of the runtime for use by a client application
that may want to do SSL client authentication.</para>
<sect3 id="gasal"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
 int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
     void *certdbhandle, int needkeydb, char *keydbpath,
    void *keydbhandle, int needsecmoddb, char *secmodpath,
    const int sslstrength);</programlisting>
</sect3>
<sect3 id="gasbh"><title>Parameters</title>
<note><para>Please see the description of the <literal>sslstrength</literal> value
and note the potential problems that can be caused by passing in wrong host
and port name values.</para></note>
<table frame="topbot" id="gasbs"><title><function>ldapssl_advclientauth_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>certdbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing certificates for your
client. You can include the database filename in the path (for example, <literal>
/usr/mozilla/</literal> <replaceable>cert_file_name</replaceable><literal>.db</literal>).
</para></entry>
</row>
<row>
<entry>
<para><literal>certdbhandle</literal></para></entry>
<entry>
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
currently used.)</para></entry>
</row>
<row>
<entry>
<para><literal>needkeydb</literal></para></entry>
<entry>
<para>Specifies whether or not the private key database needs to be opened
for use. This parameter can have one of the following values:</para>
<itemizedlist>
<listitem><para>If it is a non-zero value, the function opens the private
key database, which is identified by the <literal>keydbpath</literal> argument.</para>
</listitem>
<listitem><para>If <literal>0</literal>, the function does not open the private
key database.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>keydbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing the private key certified
by your certificate. You can include the database filename in the path (for
example,  <literal>/usr/mozilla/</literal><replaceable>key_file_name</replaceable><literal>
.db</literal>).</para></entry>
</row>
<row>
<entry>
<para><literal>needsecmoddb</literal></para></entry>
<entry>
<para>Specifies whether or not the security module database file needs to
be opened for use. This parameter can have one of the following values:</para>
<itemizedlist>
<listitem><para>If it is a non-zero value, the function opens the security
module database, which is identified by the <literal>keydbpath</literal> argument.
</para></listitem>
<listitem><para>If <literal>0</literal>, the function does not open the security
modules database.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>secmodpath</literal></para></entry>
<entry>
<para>Path to the database containing security modules. You can include the
database filename in the path (for example, <literal>/usr/mozilla/</literal><replaceable>
secmod_file_name</replaceable> <literal>.db</literal>).</para></entry>
</row>
<row>
<entry>
<para><literal>sslstrength</literal></para></entry>
<entry>
<para>Specifies how the server certificate is evaluated. It takes one of the
following:</para>
<itemizedlist>
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
the server&rsquo;s certificate without checking the for certificate authority
(CA) that issued the certificate.</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
the server&rsquo;s certificate only if you trust the CA that issued the certificate.
</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
accept the server&rsquo;s certificate only if you trust the CA that issued
the certificate and if the value of the <literal>cn</literal> attribute is
the DNS hostname of the server. If this option is selected, ensure that the <literal>
defhost</literal> parameter passed to <olink targetptr="bdavs">ldapssl_init</olink> consists
of only one hostname and not a list of hosts. Furthermore, the port number
must be passed via the  <literal>defport</literal> parameter, and cannot be
passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gascg"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasbo"><title>Description</title>
<para>You can call <function>ldapssl_advclientauth_init</function> to initialize
your client application for SSL and certificate-based client authentication.
This function is similar to <olink targetptr="bdavp">ldapssl_clientauth_init</olink> and
allows you to:</para>
<itemizedlist>
<listitem><para>Specify the name and path of a security module database.</para>
</listitem>
<listitem><para>Specify the method used to verify the server&rsquo;s certificate.
</para></listitem>
</itemizedlist>
<note><para>You must call <function>ldapssl_advclientauth_init</function> before
calling <olink targetptr="bdavs">ldapssl_init</olink> to connect to the server.</para>
</note>
</sect3>
<sect3 id="gasbt"><title>Example</title>
<para><olink targetptr="ldapssl-advclientauth-init-example">Example 21&ndash;54</olink> initializes
a client before connecting with a secure LDAP server.</para>
<example id="ldapssl-advclientauth-init-example"><title>Using <function>ldapssl_advclientauth_init
</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;ldap_ssl.h>
#include &lt;stdio.h>
...
/* Initialize client, using mozilla&rsquo;s certificate database */
if ( ldapssl_advclientauth_init( "/u/mozilla/.netscape/
               <replaceable>cert_file_name</replaceable>.db",
  NULL, 1, "/u/mozilla/.netscape/
               <replaceable>key_file_name</replaceable>.db", NULL , 1,
  "/u/mozilla/.netscape/
               <replaceable>secmod_file_name</replaceable>.db", LDAPSSL_AUTH_CNCHECK) &lt; 0 ) {
  perror( "ldap_advclientauth_init" );
    return( 1 );
  }
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasai"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines
</olink></para></sect3>
</sect2>
<sect2 id="bdavo"><title><function>ldapssl_client_init</function></title>
<para>The <function>ldapssl_client_init</function> function initializes the
secure parts (Security and SSL) of the runtime for use by your client application
to connect to a secure LDAP server over SSL.</para>
<sect3 id="gasbm"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );</programlisting>
</sect3>
<sect3 id="gasaw"><title>Parameters</title>
<table frame="topbot" id="gasbb"><title><function>ldapssl_client_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>certdbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing certificates for your
client.</para></entry>
</row>
<row>
<entry>
<para><literal>certdbhandle</literal></para></entry>
<entry>
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
used currently.)</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasbk"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasbn"><title>Description</title>
<para>You can call the <function>ldapssl_client_init</function> function to
initialize your client application for SSL. It is only called once and returns <literal>
0</literal> if all goes well. If you plan to use certificate-based authentication,
you should call either the <olink targetptr="bdavp">ldapssl_clientauth_init</olink> or
the <olink targetptr="bdavn">ldapssl_advclientauth_init</olink> function.</para>
<note><para>You must call <function>ldapssl_client_init</function> before
calling the <olink targetptr="bdavs">ldapssl_init</olink> function to connect
to the server, or the <olink targetptr="ldap-start-tls-s">ldap_start_tls_s</olink> function
to start transport layer security.</para></note>
</sect3>
<sect3 id="gasbx"><title>Example</title>
<para><olink targetptr="ldapssl-client-init-example">Example 21&ndash;55</olink> 
initializes a client before connecting with a secure LDAP server.</para>
<example id="ldapssl-client-init-example"><title>Using <function>ldapssl_client_init
</function></title>
<programlisting role="fragment">#include &lt;ldap.h>
#include &lt;ldap_ssl.h>
#include &lt;stdio.h>
...
/* Initialize client using a certificate database
   copied from &cnDirectoryServer;. */
if ( ldapssl_client_init( "/local/client/alias/", NULL ) &lt; 0) {
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}</programlisting>
<para>The <parameter>certdbpath</parameter> is a path to the file system directory
containing the certificate database files. For example:</para>
<screen>$ ls /local/client/alias/*.db
/local/client/alias/cert8.db
/local/client/alias/key3.db
/local/client/alias/secmod.db
$</screen>
</example>
</sect3>
<sect3 id="gasce"><title>See Also</title>
<para><olink targetptr="ldap-start-tls-s">ldap_start_tls_s</olink>, <olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines
</olink></para></sect3>
</sect2>
<sect2 id="bdavp"><title><function>ldapssl_clientauth_init</function></title>
<para>The <function>ldapssl_clientauth_init</function> function initializes
your client application to connect to a secure LDAP server over SSL and to
use certificate-based client authentication.</para>
<sect3 id="gasag"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
     int needkeydb, char *keydbpath, void *keydbhandle );</programlisting>
</sect3>
<sect3 id="gascb"><title>Parameters</title>
<table frame="topbot" id="gasan"><title><function>ldapssl_clientauth_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>certdbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing certificates for your
client. You can include the database filename in the path (for example, <literal>
/usr/mozilla/</literal> <replaceable>cert_file_name</replaceable><literal>.db</literal>).
</para></entry>
</row>
<row>
<entry>
<para><literal>needkeydb</literal></para></entry>
<entry>
<para>Specifies whether or not the private key database needs to be opened
for use. This parameter can have one of the following values:</para>
<itemizedlist>
<listitem><para>If it is a non-zero value, the function opens the private
key database, which is identified by the keydbpath argument.</para></listitem>
<listitem><para>If <literal>0</literal>, the function does not open the private
key database.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>keydbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing the private key certified
by your certificate. You can include the database filename in the path (for
example, /usr/mozilla/ <replaceable>key_file_name</replaceable>.db).</para>
</entry>
</row>
<row>
<entry>
<para><literal>certdbhandle</literal></para></entry>
<entry>
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
currently used.)</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasav"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasat"><title>Description</title>
<para>You can call the <function>ldapssl_clientauth_init</function> function
to initialize your client application for SSL and certificate-based client
authentication. However, if you need to specify the name and path of the security
modules database or if you need to specify how the server&rsquo;s certificate
will be verified, you should call the <function>ldapssl_advclientauth_init</function> function
instead.</para>
<note><para>You must call <function>ldapssl_clientauth_init</function> before
calling <olink targetptr="bdavs">ldapssl_init</olink> to connect to the server.</para>
</note>
</sect3>
<sect3 id="gasbr"><title>Example</title>
<para><olink targetptr="ldapssl-clientauth-init-example">Example 21&ndash;56</olink> 
initializes a client before connecting with a secure LDAP server.</para>
<example id="ldapssl-clientauth-init-example"><title>Using <function>ldapssl_clientauth_init
</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;ldap_ssl.h>
#include &lt;stdio.h>
...
/* Initialize client, using mozilla&rsquo;s certificate database */
if ( ldapssl_clientauth_init( "/u/mozilla/.netscape/
               <replaceable>cert_file_name</replaceable>.db", NULL, 1,
  "/u/mozilla/.netscape/
               <replaceable>key_file_name</replaceable>.db", NULL ) &lt; 0 ) {
  perror( "ldap_clientauth_init" );
    return( 1 );
  }
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasbq"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink></para></sect3>
</sect2>
<sect2 id="bdavq"><title><function>ldapssl_enable_clientauth</function></title>
<para>The <function>ldapssl_enable_clientauth</function> function enables
SSL client authentication on the given connection (passed using the <literal>ld</literal> parameter).
</para>
<sect3 id="gasbg"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
    char *keypasswd, char *certnickname );</programlisting>
</sect3>
<sect3 id="gasbl"><title>Parameters</title>
<table frame="topbot" id="gasbv"><title><function>ldapssl_enable_clientauth</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>keynickname</literal></para></entry>
<entry>
<para>Pass an empty string, <literal>""</literal>, for this value. (This parameter
is not currently used.)</para></entry>
</row>
<row>
<entry>
<para><literal>keypasswd</literal></para></entry>
<entry>
<para>Password to the encrypted private key database.</para></entry>
</row>
<row>
<entry>
<para><literal>certnickname</literal></para></entry>
<entry>
<para>Nickname of the certificate that you want to use for client authentication.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasbd"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasao"><title>See Also</title>
<para><olink targetptr="bdavp">ldapssl_clientauth_init</olink></para></sect3>
</sect2>
<sect2 id="bdavr"><title><function>ldapssl_err2string</function></title>
<para>The <function>ldapssl_err2string</function> function returns the corresponding
error message for an SSL-specific error code.</para>
<sect3 id="gasbw"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
 const char * LDAP_CALL ldapssl_err2string ( const int prerrno );</programlisting>
</sect3>
<sect3 id="gasam"><title>Parameters</title>
<table frame="topbot" id="gasef"><title><function>ldapssl_err2string</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>prerrno</literal></para></entry>
<entry>
<para>The SSL error code that you want interpreted into an error message.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gascj"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns the corresponding error message for
the given error code.</para></listitem>
<listitem><para>If unsuccessful (for example, if the error code is not a known
SSL error code), returns a pointer to the string <literal>Unknown error.</literal></para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gasck"><title>Description</title>
<para><function>ldapssl_err2string</function> provides support for SSL-specific
error messages that are not covered by the regular message routine  <olink targetptr="bdarq">ldap_err2string</olink>. If any <function>ldapssl_*</function> function
returns an error code that is unknown to <olink targetptr="bdarq">ldap_err2string
</olink>&ndash;it returns <literal>Unknown error</literal>&ndash; this function
should be called to determine the SSL-specific error message. To check for
SSL errors, call <function>ldapssl_err2string</function>  after you call any
of the following SSL initialization functions:</para>
<itemizedlist>
<listitem><para><olink targetptr="bdavo">ldapssl_client_init</olink></para>
</listitem>
<listitem><para><olink targetptr="bdavp">ldapssl_clientauth_init</olink></para>
</listitem>
<listitem><para><olink targetptr="bdavn">ldapssl_advclientauth_init</olink></para>
</listitem>
<listitem><para><olink targetptr="bdavu">ldapssl_pkcs_init</olink></para><para>The
errors returned by these functions are usually related to certificate database
corruption, missing certificates in a certificate database, client authentication
failures, and other general SSL errors.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasdg"><title>See Also</title>
<para><olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavn">ldapssl_advclientauth_init
</olink>, <olink targetptr="bdavu">ldapssl_pkcs_init</olink>, <olink targetptr="bdarq">ldap_err2string</olink></para></sect3>
</sect2>
<sect2 id="bdavs"><title><function>ldapssl_init</function></title>
<para>The <function>ldapssl_init</function> function initializes the LDAP
library for SSL and installs the I/O routines for SSL.</para>
<sect3 id="gasdy"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
 LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );</programlisting>
</sect3>
<sect3 id="gascv"><title>Parameters</title>
<table frame="topbot" id="gascs"><title><function>ldapssl_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>defhost</literal></para></entry>
<entry>
<para>Connect to this LDAP server, if no other server is specified.</para>
</entry>
</row>
<row>
<entry>
<para><literal>defport</literal></para></entry>
<entry>
<para>Connect to this server port, if no other port is specified. To specify
the default port 389, use <literal>LDAP_PORT</literal> as the value for this
parameter.</para></entry>
</row>
<row>
<entry>
<para><literal>defsecure</literal></para></entry>
<entry>
<para>Determines whether or not to establish the default connection over SSL.
Set this to a non-zero value to establish the default connection over SSL.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gascy"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdakj">LDAP
</olink>  structure, which should be passed to subsequent calls to other LDAP
API functions.</para></listitem>
<listitem><para>If unsuccessful, returns <returnvalue>-1</returnvalue>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gascx"><title>Description</title>
<para><function>ldapssl_init</function> allocates an <olink targetptr="bdakj">LDAP
</olink>  structure but does not open an initial connection. Before calling
this function, call <olink targetptr="bdavo">ldapssl_client_init</olink> to
initialize your client for SSL.</para>
<note><para>Calling this function is equivalent to calling <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init</olink> (IPv6)
followed by <olink targetptr="bdavt">ldapssl_install_routines</olink>  and <olink targetptr="bdavg">ldap_set_option</olink> to set the <literal>LDAP_OPT_SSL</literal> option
to <literal>LDAP_OPT_ON</literal>.</para></note>
</sect3>
<sect3 id="gasds"><title>Example</title>
<para><olink targetptr="ldapssl-init-example">Example 21&ndash;57</olink> connects
your client to a secure LDAP server.</para>
<example id="ldapssl-init-example"><title>Using <function>ldapssl_init</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;ldap_ssl.h>
#include &lt;stdio.h>
...
/* Initialize client, using mozilla&rsquo;s certificate database */
if ( ldapssl_client_init( "/u/mozilla/.netscape/
               <replaceable>cert_file_name</replaceable>.db", NULL ) &lt; 0) {
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}
/* get a handle to an LDAP connection */
if ( (ld = ldapssl_init( "cert.example.com", LDAPS_PORT, 1 )) == NULL {
  perror( "ldapssl_init" );
  return( 1 );
}
...
/* Client can now perform LDAP operations on the secure LDAP server */
...</programlisting>
</example>
</sect3>
<sect3 id="gasdm"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink></para></sect3>
</sect2>
<sect2 id="bdavt"><title><function>ldapssl_install_routines</function></title>
<para>The <function>ldapssl_install_routines</function> function installs
the I/O routines that enable SSL over LDAP.</para>
<sect3 id="gasdq"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
 int ldapssl_install_routines( LDAP *ld );</programlisting>
</sect3>
<sect3 id="gascu"><title>Parameters</title>
<table frame="topbot" id="gasdc"><title><function>ldapssl_install_routines</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gascm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gascz"><title>Description</title>
<para>You need to call <function>ldapssl_install_routines</function> in combination
with <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init
</olink> (IPv6) and <olink targetptr="bdavg">ldap_set_option</olink>. As an
alternative, you can call <olink targetptr="bdavs">ldapssl_init</olink> rather
than these three functions.</para>
<note><para>As is the case with the <olink targetptr="bdavs">ldapssl_init</olink> function,
you need to call <olink targetptr="bdavo">ldapssl_client_init</olink> to initialize
your client for SSL before calling <function>ldapssl_install_routines</function>.
</para></note>
</sect3>
<sect3 id="gasdh"><title>Example</title>
<para><olink targetptr="ldapssl-install-routines-example-example">Example
21&ndash;58</olink> connects your client to a secure LDAP server.</para>
<example id="ldapssl-install-routines-example-example"><title>Using <function>ldapssl_install_routines
</function></title>
<programlisting>#include &lt;ldap.h>
#include &lt;ldap_ssl.h>
#include &lt;stdio.h>
...
/* Initialize client, using mozilla&rsquo;s certificate database */
if ( ldapssl_client_init( "/u/mozilla/.netscape/
               <replaceable>cert_file_name</replaceable>.db", NULL ) &lt; 0) {
  printf( "Failed to initialize SSL client...\n" );
  return( 1 );
}
/* Get the handle to an LDAP connection. Use prldap_init() for IPv6. */
if ( (ld = ldap_init( MY_HOST, 636 )) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}

/* Load SSL routines */
if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldapssl_install_routines" );
  return( 1 );
}

/* Set the option to use SSL with the default connection */
if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) {
  ldap_perror( ld, "ldap_set_option" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gaseb"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavo">ldapssl_client_init</olink></para></sect3>
</sect2>
<sect2 id="bdavu"><title><function>ldapssl_pkcs_init</function></title>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility.</para>
</note>
<para>The <function>ldap_pcks_init</function> function provides thread-safe
SSL initialization.</para>
<sect3><title>Syntax</title>
<programlisting>int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns);</programlisting>
</sect3>
<sect3 id="gasdp"><title>Description</title>
<para>The <function>ldap_pkcs_init</function> structure sets up callbacks
for the security library to obtain required runtime information. It should
be used in place of <olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, and <olink targetptr="bdavn">ldapssl_advclientauth_init
</olink>.</para>
<note><para>The &DirectorySDKForC; uses the Public Key Cryptography Standard
(PKCS) API implemented in Network Security Services (NSS) to provide SSL security
support. Specifically, NSS implements the security API as defined in the PKCS#11
standard.</para></note>
<para>Because <function>ldap_pkcs_init</function> is based on the <literal>ldapssl_pkcs_fns
</literal> structure, you do not need to know all of the security parameters
at initialization, unlike the other SSL initialization functions (<function>ldapssl_*_init
</function>), which require all security parameters to be known at the time
of initialization. <olink targetptr="ldapssl-pkcs-fns-example">Example 21&ndash;59
</olink> defines the <literal>ldapssl_pkcs_fns</literal> structure.</para>
<example id="ldapssl-pkcs-fns-example"><title><structname>ldapssl_pkcs_fns</structname> Structure
Definition</title>
<programlisting>typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK)
  (void *context, char **tokenname);
typedef int (LDAP_PKCS_GET_PIN_CALLBACK)
  (void *context, const char *tokenname, char **tokenpin);
typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK)
  (void *context, char **certpath);
typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context,
  char **keypath);
typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK)
  (void *context, char **modulepath);
typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK)
  (void *context, char **certname);
typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK)
  (void *context, char **filename);

#define PKCS_STRUCTURE_ID 1
struct ldapssl_pkcs_fns {
  int local_structure_id;
  void *local_data;
  LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath;
  LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname;
  LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath;
  LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath;
  LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin;
  LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname;
  LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
};</programlisting>
</example>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot"><title><function>ldapssl_pkcs_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>pfns</literal></para></entry>
<entry>
<para>Specifies the <literal>ldap_pkcs_fns</literal> structure for initialization.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasdt"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para>0 is successful.</para></listitem>
<listitem><para>-1 if unsuccessful.</para></listitem>
<listitem><para><replaceable>n</replaceable> (a positive integer) denotes
a Netscape Portable Runtime (NSPR) error as returned by the <function>PR_GetError
</function> NSPR function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasdi"><title>See Also</title>
<para><olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavn">ldapssl_advclientauth_init
</olink></para></sect3>
</sect2>
<sect2 id="bdavv"><title><function>ldapssl_serverauth_init</function></title>
<para>The <function>ldapssl_serverauth_init</function> function is a server-authentication
only version of <olink targetptr="bdavp">ldapssl_clientauth_init</olink>.</para>
<sect3 id="gascp"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int ldapssl_serverauth_init(
    const char *certdbpath, void *certdbhandle, const int sslstrength );</programlisting>
</sect3>
<sect3 id="gasdj"><title>Parameters</title>
<note><para>Please see the description of the <literal>sslstrength</literal> value
and note the potential problems that can be caused by passing in wrong host
and port name values.</para></note>
<table frame="topbot" id="gascn"><title><function>ldapssl_serverauth_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>certdbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing certificates for your
client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
</para></entry>
</row>
<row>
<entry>
<para><literal>certdbhandle</literal></para></entry>
<entry>
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
currently used.)</para></entry>
</row>
<row>
<entry>
<para><literal>sslstrength</literal></para></entry>
<entry>
<para>Specifies how the server certificate is evaluated. It takes one of the
following:</para>
<itemizedlist>
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
the server&rsquo;s certificate without checking the for certificate authority
(CA) that issued the certificate.</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
the server&rsquo;s certificate only if you trust the CA that issued the certificate.
</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
accept the server&rsquo;s certificate only if you trust the CA that issued
the certificate and if the value of the <literal>cn</literal> attribute is
the DNS hostname of the server. If this option is selected, please ensure
that the <literal>defhost</literal> parameter passed to <olink targetptr="bdavs">
ldapssl_init</olink> consists of only one hostname and not a list of hosts.
Furthermore, the port number must be passed via the  <literal>defport</literal> parameter,
and cannot be passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaseg"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> if successful.</para></listitem>
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasdw"><title>Description</title>
<para><function>ldapssl_serverauth_init</function> is a server-authentication
only version of <olink targetptr="bdavp">ldapssl_clientauth_init</olink>.
 This function allows the <literal>sslstrength</literal> parameter to be passed
in.</para></sect3>
<sect3 id="gasde"><title>See Also</title>
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init
</olink></para></sect3>
</sect2>
<sect2 id="bdavw"><title><function>ldapssl_set_strength</function></title>
<para>The <function>ldapssl_set_strength</function> sets the SSL strength
for an existing SSL-enabled LDAP session handle.</para>
<sect3 id="gasdo"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );</programlisting>
</sect3>
<sect3 id="gascl"><title>Parameters</title>
<note><para>See the description of the <literal>sslstrength</literal> value
and note the potential problems that can be caused by passing in wrong host
and port name values.</para></note>
<table frame="topbot" id="gasee"><title><function>ldapssl_set_strength</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server. If value is <literal>NULL</literal>,
the default for the new LDAP session handles is set.</para></entry>
</row>
<row>
<entry>
<para><literal>sslstrength</literal></para></entry>
<entry>
<para>Specifies how the server certificate is evaluated. It takes one of the
following:</para>
<itemizedlist>
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
the server&rsquo;s certificate without checking the for certificate authority
(CA) that issued the certificate.</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
the server&rsquo;s certificate only if you trust the CA that issued the certificate.
</para></listitem>
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
accept the server&rsquo;s certificate only if you trust the CA that issued
the certificate and if the value of the <literal>cn</literal> attribute is
the DNS hostname of the server. If this option is selected, please ensure
that the <literal>defhost</literal> parameter passed to <olink targetptr="bdavs">
ldapssl_init</olink> consists of only one hostname and not a list of hosts.
Furthermore, the port number must be passed via the  <literal>defport</literal> parameter,
and cannot be passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdavx"><title><function>ldapssl_tls_start_s</function></title>
<para>The <function>ldapssl_tls_start_s</function> function starts an SSL
handshake on a previously established non-secure connection.</para>
<sect3 id="gasdk"><title>Syntax</title>
<programlisting>#include &lt;ldap_ssl.h>
 LDAP_API(int)  LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure,
    char *certdbpath, char *keydbpath, char ***referralsp );</programlisting>
</sect3>
<sect3 id="gasec"><title>Parameters</title>
<table frame="topbot" id="gasdv"><title><function>ldapssl_tls_start_s</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>defsecure</literal></para></entry>
<entry>
<para>Determines whether or not to establish the default connection over SSL.
Set this to a non-zero value to establish the default connection over SSL.</para>
</entry>
</row>
<row>
<entry>
<para><literal>certdbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing certificates for your
client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
</para></entry>
</row>
<row>
<entry>
<para><literal>keydbpath</literal></para></entry>
<entry>
<para>Specifies the path to the database containing the private key certified
by your certificate. You can include the database filename in the path (for
example,  <literal>/usr/mozilla/</literal><replaceable>key_file_name</replaceable><literal>
.db</literal>).</para></entry>
</row>
<row>
<entry>
<para><literal>referralsp</literal></para></entry>
<entry>
<para>Pointer to an array of strings representing the referrals found by an
LDAP search operation and returned by the server (applicable only if the LDAP
operation was a search operation). When done, you can free this by calling
the <function>ldap_value_free</function> function.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasea"><title>Description</title>
<para>The <function>ldapssl_tls_start_s</function> function starts an SSL
handshake on a previously established non-secure connection.</para></sect3>
</sect2>
<sect2 id="bdavy"><title><function>ldap_str2charray</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_str2charray</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_str2charray</function></primary>
</indexterm>
<para>This function is deprecated and should not be used. It is included in
 <literal>ldap-deprecated.h</literal> for backward-compatibility.</para>
<sect3 id="bdavz"><title><function>ldap_tmplattrs</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_tmplattrs</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_tmplattrs</function></primary>
</indexterm>
<para>The <function>ldap_tmplattrs</function> function obtains a pointer to
the correct  <literal>ldap_disptmpl</literal> structure.</para></sect3>
<sect3 id="gased"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs,
    int exclude, unsigned long syntaxmask );</programlisting>
</sect3>
<sect3 id="gasci"><title>Parameters</title>
<table frame="topbot" id="gasdd"><title><function>ldap_tmplattrs</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>tmpl</literal></para></entry>
<entry>
<para>The name of the template to be retrieved.</para></entry>
</row>
<row>
<entry>
<para><literal>includeattrs</literal></para></entry>
<entry>
<para>A null terminated array of attributes that should always be included
(it may be <literal>NULL</literal> if no extra attributes are required).</para>
</entry>
</row>
<row>
<entry>
<para><literal>exclude</literal></para></entry>
<entry>
<para>If <literal>0</literal>, only attributes where the logical AND of the
template item syntax id and the <parameter>syntaxmask</parameter> is non-zero
are included. If non-zero, attributes where the logical AND of the template
item syntax id and the <parameter>syntaxmask</parameter> is non-zero are excluded.
</para></entry>
</row>
<row>
<entry>
<para><literal>syntaxmask</literal></para></entry>
<entry>
<para>When non-zero, it is used to restrict the attribute set returned.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasdz"><title>Returns</title>
<itemizedlist>
<listitem><para><literal>A NULL</literal> terminated array that contains the
names of attributes that need to be retrieved if the template, defined by <literal>
tmpl</literal> , is to be used to display an entry.</para></listitem>
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasdl"><title>Description</title>
<para>The attribute list should be freed using <olink targetptr="bdaxc">ldap_value_free
</olink> .</para></sect3>
<sect3 id="gasdx"><title>See Also</title>
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></sect3>
</sect2>
<sect2 id="bdawa"><title><function>ldap_tmplerr2string</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_tmplerr2string</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_tmplerr2string</function></primary>
</indexterm>
<para>The <function>ldap_templerr2string</function> function returns a string
representation of the error passed in the parameter.</para>
<sect3 id="gasch"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 char * ldap_tmplerr2string( int err );</programlisting>
</sect3>
<sect3 id="gasdf"><title>Parameters</title>
<table frame="topbot" id="gaseh"><title><function>ldap_tmplerr2string</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>err</literal></para></entry>
<entry>
<para>Error returned.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawb"><title><function>ldap_ufn_search_c</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_ufn_*</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_ufn_*</function></primary>
</indexterm>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
<sect3 id="bdawc"><title><function>ldap_ufn_search_ct</function></title>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
</sect3>
</sect2>
<sect2 id="bdawd"><title><function>ldap_ufn_search_s</function></title>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
<sect3 id="bdawe"><title><function>ldap_ufn_setfilter</function></title>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
</sect3>
</sect2>
<sect2 id="bdawf"><title><function>ldap_ufn_setprefix</function></title>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
<sect3 id="bdawg"><title><function>ldap_ufn_timeout</function></title>
<note><para>This function will be deprecated and should not be used. It is
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
</para></note>
</sect3>
</sect2>
<sect2 id="bdawh"><title><function>ldap_unbind</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_unbind</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_unbind</function></primary>
</indexterm>
<para>The <function>ldap_unbind</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the
 <olink targetptr="bdakj">LDAP</olink> structure.</para>
<sect3 id="gasco"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_unbind( LDAP *ld );</programlisting>
</sect3>
<sect3 id="gasda"><title>Parameters</title>
<table frame="topbot" id="gascr"><title><function>ldap_unbind</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gascw"><title>Returns</title>
<para>For a list of possible results for an LDAP unbind operation, see  <olink targetptr="bdawi">ldap_unbind_s</olink>.</para></sect3>
<sect3 id="gascq"><title>Description</title>
<para>The <function>ldap_unbind</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the
 <olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions
(<olink targetptr="bdawh">ldap_unbind</olink> , <olink targetptr="bdawi">ldap_unbind_s
</olink>, and  <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work
synchronously in the sense that they send an unbind request to the server,
close all open connections associated with the LDAP session handle, and dispose
of all resources associated with the session handle before returning.</para>
<note><para>There is no server response to an LDAP unbind operation. All three
of the unbind functions return <errorcode>LDAP_SUCCESS</errorcode> (or another
LDAP error code if the request cannot be sent to the LDAP server). After a
call to one of the unbind functions, the session handle <literal>ld</literal> is
invalid and it is illegal to make any further calls using it.</para></note>
</sect3>
<sect3 id="gasdb"><title>Example</title>
<para><olink targetptr="ldap-unbind-example">Example 21&ndash;60</olink> closes
the current connection with the LDAP server.</para>
<example id="ldap-unbind-example"><title>Using <function>ldap_unbind</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
...
/* After completing your LDAP operations with the server, close the
   connection. */
if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Error while unbinding from the directory" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasct"><title>See Also</title>
<para><olink targetptr="bdawi">ldap_unbind_s</olink>,  <olink targetptr="bdawj">ldap_unbind_ext
</olink></para></sect3>
</sect2>
<sect2 id="bdawi"><title><function>ldap_unbind_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_unbind_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_unbind_s</function></primary>
</indexterm>
<para>The <function>ldap_unbind_s</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
<sect3 id="gasdn"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_unbind_s( LDAP *ld );</programlisting>
</sect3>
<sect3 id="gasdr"><title>Parameters</title>
<table frame="topbot" id="gasdu"><title><function>ldap_unbind_s</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasgg"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasfd"><title>Description</title>
<para>The <function>ldap_unbind_s</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions ( <olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink>,
and <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work synchronously
in the sense that they send an unbind request to the server, close all open
connections associated with the LDAP session handle, and dispose of all resources
associated with the session handle before returning.</para>
<note><para>There is no server response to an LDAP unbind operation. All three
of the unbind functions return <errorcode>LDAP_SUCCESS</errorcode> (or another
LDAP error code if the request cannot be sent to the LDAP server). After a
call to one of the unbind functions, the session handle <literal>ld</literal> is
invalid and it is illegal to make any further calls using it.</para></note>
</sect3>
<sect3 id="gasga"><title>Example</title>
<para><olink targetptr="ldap-unbind-s-example">Example 21&ndash;61</olink> closes
the current connection with the LDAP server.</para>
<example id="ldap-unbind-s-example"><title>Using <function>ldap_unbind_s</function></title>
<programlisting>#include &lt;ldap.h>
...
LDAP *ld;
...
/* After completing your LDAP operations with the server, close the
   connection. */
if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "Error while unbinding from the directory" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasej"><title>See Also</title>
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawj">ldap_unbind_ext
</olink></para></sect3>
</sect2>
<sect2 id="bdawj"><title><function>ldap_unbind_ext</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_unbind_ext</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_unbind_ext</function></primary>
</indexterm>
<para>The <function>ldap_unbind_ext</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
<sect3 id="gasew"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
    LDAPControl **clientctrls );</programlisting>
</sect3>
<sect3 id="gaset"><title>Parameters</title>
<table frame="topbot" id="gasfa"><title><function>ldap_unbind_ext</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>List of LDAP server controls.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>List of client controls.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasgh"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gasfi"><title>Description</title>
<para>The <function>ldap_unbind_ext</function> function unbinds from the directory,
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions (<olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink>,
and <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work synchronously
in the sense that they send an unbind request to the server, close all open
connections associated with the LDAP session handle, and dispose of all resources
associated with the session handle before returning.</para>
<note><para>Unlike the other two unbind functions, <function>ldap_unbind_ext</function> allows
you to explicitly include both server and client controls in your unbind request.
However, since there is no server response to an unbind request, there is
no way to receive a response from a server control that is included.</para>
</note>
</sect3>
<sect3 id="gasff"><title>See Also</title>
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s
</olink></para></sect3>
</sect2>
<sect2 id="bdawk"><title><function>ldap_url_parse</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_url_parse</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_url_parse</function></primary>
</indexterm>
<para>The <function>ldap_url_parse</function> function parses an LDAP URL
into its components.</para>
<sect3 id="gasex"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );</programlisting>
</sect3>
<sect3 id="gasel"><title>Parameters</title>
<table frame="topbot" id="gasfj"><title><function>ldap_url_parse</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>The URL that you want to check.</para></entry>
</row>
<row>
<entry>
<para><literal>ludpp</literal></para></entry>
<entry>
<para>Pointer to a structure containing the components of the URL.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasfp"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><literal>LDAP_URL_ERR_NOTLDAP</literal> if the URL does not
begin with the <literal>ldap://</literal> or <literal>ldaps:// prefix</literal>.</para>
</listitem>
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if the URL missing trailing
slash after host or port.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_BADSCOPE</literal> if the scope within
the URL is invalid.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_MEM</literal> if not enough free memory
is available for this operation.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_PARAM</literal> if an invalid argument
was passed to the function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasfb"><title>Example</title>
<para><olink targetptr="ldap-url-parse-example-code">Example 21&ndash;62</olink> parses
an LDAP URL and prints out each component of it.</para>
<example id="ldap-url-parse-example-code"><title>Using <function>ldap_url_parse</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
char *my_url = "ldap://ldap.example.com:1389/dc=example,dc=com?
                cn,mail,telephoneNumber?sub?(sn=Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &amp;ludpp ) ) != 0 ) {
  switch( res ){
    case LDAP_URL_ERR_NOTLDAP:
      printf( "URL does not begin with \"ldap://\"\n" );
      break;
    case LDAP_URL_ERR_NODN:
      printf( "URL missing trailing slash after host or port\n" );
      break;
    case LDAP_URL_ERR_BADSCOPE:
      printf( "URL contains an invalid scope\n" );
      break;
    case LDAP_URL_ERR_MEM:
      printf( "Not enough memory\n" );
      break;
    default:
      printf( "Unknown error\n" );
  }
  return( 1 );
}
printf( "Components of the URL:\n" );
printf( "Host name: %s\n", ludpp->lud_host );
printf( "Port number: %d\n", ludpp->lud_port );
if ( ludpp->lud_dn != NULL ) {
  printf( "Base entry: %s\n", ludpp->lud_dn );
} else {
  printf( "Base entry: Root DN\n" );
}
if ( ludpp->lud_attrs != NULL ) {
  printf( "Attributes returned: \n" );
  for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) {
    printf( "\t%s\n", ludpp->lud_attrs[i] );
}
} else {
        printf( "No attributes returned.\n" );
}
printf( "Scope of the search: " );
switch( ludpp->lud_scope ) {
  case LDAP_SCOPE_BASE:
    printf( "base\n" );
    break;
  case LDAP_SCOPE_ONELEVEL:
    printf( "one\n" );
    break;
  case LDAP_SCOPE_SUBTREE:
    printf( "sub\n" );
    break;
  default:
    printf( "Unknown scope\n" );
}
printf( "Filter: %s\n", ludpp->lud_filter );
...</programlisting>
</example>
</sect3>
<sect3 id="gaser"><title>See Also</title>
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></sect3>
</sect2>
<sect2 id="bdawl"><title><function>ldap_url_parse_no_defaults</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_url_parse_no_defaults</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_url_parse_no_defaults</function></primary>
</indexterm>
<para>The <function>ldap_url_parse_no_defaults</function> function parses
an LDAP URL into its components.</para>
<sect3 id="gasfw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_url_parse_no_defaults( const char *url, LDAPURLDesc **ludpp,
     int dn_required );</programlisting>
</sect3>
<sect3 id="gaseq"><title>Parameters</title>
<table frame="topbot" id="gasfy"><title><function>ldap_url_parse_no_defaults</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>The URL that you want to check.</para></entry>
</row>
<row>
<entry>
<para><literal>ludpp</literal></para></entry>
<entry>
<para>Pointer to a structure containing the components of the URL.</para>
</entry>
</row>
<row>
<entry>
<para><literal>dn_required</literal></para></entry>
<entry>
<para>Specifies if a DN must be present in the URL. Set to <literal>0</literal>,
the DN is not required. Set to <literal>1</literal>, the function will return
an error <literal>LDAP_URL_ERR_NODN</literal> if no DN is present.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasfm"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if a required DN is not
present.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_NOTLDAP</literal> if the URL does not
begin with the ldap:// or ldaps:// prefix.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if the URL missing trailing
slash after host or port.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_BADSCOPE</literal> if the scope within
the URL is invalid.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_MEM</literal> if not enough free memory
is available for this operation.</para></listitem>
<listitem><para><literal>LDAP_URL_ERR_PARAM</literal> if an invalid argument
was passed to the function.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasez"><title>Description</title>
<para>The <function>ldap_url_parse_no_defaults</function> function does not
set any default value in the fields that would be absent from the URL (for
example, the port number).</para></sect3>
</sect2>
<sect2 id="bdawm"><title><function>ldap_url_search</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_url_search</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_url_search</function></primary>
</indexterm>
<para>The <function>ldap_url_search</function> function searches the directory
asynchronously for matching entries, based on the contents of the URL.</para>
<sect3 id="gasfv"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_url_search( LDAP *ld, const char *url, int attrsonly );</programlisting>
</sect3>
<sect3 id="gasfl"><title>Parameters</title>
<table frame="topbot" id="gasem"><title><function>ldap_url_search</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>LDAP URL specifying a search of the directory.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasfc"><title>Returns</title>
<para>Returns the message ID of the <olink targetptr="bdawm">ldap_url_search</olink> operation.
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> 
and <olink targetptr="bdauv">ldap_result2error</olink>.</para></sect3>
<sect3 id="gasfz"><title>Description</title>
<para><function>ldap_url_search</function> searches the directory for matching
entries, based on the contents of the URL. <function>ldap_url_search</function> is
an asynchronous function; it does not directly return results. If you want
the results to be returned directly by the function, call the synchronous
function  <olink targetptr="bdawn">ldap_url_search_s</olink>.</para></sect3>
<sect3 id="gasft"><title>Example</title>
<para><olink targetptr="ldap-url-search-example-code">Example 21&ndash;63</olink> returns
the message ID.</para>
<example id="ldap-url-search-example-code"><title>Using <function>ldap_url_search
</function></title>
<programlisting>#include "examples.h"

static void do_other_work();
unsigned long global_counter = 0;

int
main( int argc, char **argv )
{
  char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
                  cn,mail,telephoneNumber?sub?(sn=Jensen)";
  LDAP *ld;
  LDAPMessage *result, *e;
  BerElement *ber;
  char *a, *dn;
  char **vals;
  int i, rc, finished, msgid;
  int num_entries = 0;
  struct timeval zerotime;

  zerotime.tv_sec = zerotime.tv_usec = 0L;

/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
  perror( "ldap_init" );
  return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_simple_bind_s" );
  return( 1 );
}
/* search for all entries with surname of Jensen */
if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) {
  ldap_perror( ld, "ldap_url_search" );
  return( 1 );
}

/* Loop, polling for results until finished */
finished = 0;
while ( !finished ) {
  /*
  * Poll for results.   We call ldap_result with the "all" parameter
  * set to zero. This causes ldap_result() to return exactly one
  * entry if at least one entry is available. This allows us to
  * display the entries as they are received.
  */
  result = NULL;
  rc = ldap_result( ld, msgid, 0, &amp;zerotime, &amp;result );
  switch ( rc ) {
  case -1:
    /* some error occurred */
    ldap_perror( ld, "ldap_result" );
    return( 1 );
  case 0:
  /* Timeout was exceeded. No entries are ready for retrieval. */
    if ( result != NULL ) {
      ldap_msgfree( result );
    }
    break;
  default:
  /*
  * Either an entry is ready for retrieval, or all entries have
  * been retrieved.
  */
    if (( e = ldap_first_entry( ld, result )) == NULL ) {
      /* All done */
      finished = 1;
      if ( result != NULL ) {
        ldap_msgfree( result );
      }
      continue;
      }
    /* for each entry print out name + all attrs and values */
    num_entries++;
    if (( dn = ldap_get_dn( ld, e )) != NULL ) {
      printf( "dn: %s\n", dn );
      ldap_memfree( dn );
    }
    for ( a = ldap_first_attribute( ld, e, &amp;ber );
     a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
      if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
        for ( i = 0; vals[ i ] != NULL; i++ ) {
          printf( "%s: %s\n", a, vals[ i ] );
        }
      ldap_value_free( vals );
      }
      ldap_memfree( a );
    }
    if ( ber != NULL ) {
      ldap_ber_free( ber, 0 );
    }
    printf( "\n" );
    ldap_msgfree( result );
  }
  /* Do other work here while you are waiting... */
  do_other_work();
}

/* All done. Print a summary. */
printf( "%d entries retrieved. I counted to %ld "
      "while I was waiting.\n", num_entries,
      global_counter );
ldap_unbind( ld );
return( 0 );
}

/*
 * Perform other work while polling for results. */
static void
do_other_work()
{
    global_counter++;
}</programlisting>
</example>
</sect3>
<sect3 id="gasei"><title>See Also</title>
<para><olink targetptr="bdawn">ldap_url_search_s</olink>,  <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauv">ldap_result2error
</olink></para></sect3>
</sect2>
<sect2 id="bdawn"><title><function>ldap_url_search_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_url_search_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_url_search_s</function></primary>
</indexterm>
<para>The <function>ldap_url_search_s</function> function searches the directory
synchronously for matching entries, based on the contents of the URL.</para>
<sect3 id="gaseu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_url_search_s( LDAP *ld, const char *url,
     int attrsonly, LDAPMessage **res );</programlisting>
</sect3>
<sect3 id="gasfk"><title>Parameters</title>
<table frame="topbot" id="gasge"><title><function>ldap_url_search_s</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>LDAP URL specifying a search of the directory.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Results of the search (when the call is completed).</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasep"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful, returns the LDAP error code for the operation.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="gasfo"><title>Description</title>
<para>The <function>ldap_url_search_s</function> function searches the directory
for matching entries, based on the contents of the URL. <function>ldap_url_search_s
</function> is a synchronous function, which directly returns the results
of the operation. If you want to perform other operations while waiting for
the results of this operation, call the asynchronous function <olink targetptr="bdawm">ldap_url_search</olink>.</para></sect3>
<sect3 id="gasfg"><title>Example</title>
<para><olink targetptr="ldap-url-search-s-example">Example 21&ndash;64</olink> 
processes a search request from an LDAP URL.</para>
<example id="ldap-url-search-s-example"><title>Using <function>ldap_url_search_s</function></title>
<programlisting>#include &lt;stdio.h>
#include &lt;ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
                cn,mail,telephoneNumber?sub?(sn=Jensen)";
...
/* Process the search request in the URL */
if ( ldap_url_search_s( ld, my_url, 0, &amp;result ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_url_search_s" );
  return( 1 );
}
...</programlisting>
</example>
</sect3>
<sect3 id="gasgf"><title>See Also</title>
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavc">ldap_search_st
</olink></para></sect3>
</sect2>
<sect2 id="bdawo"><title><function>ldap_url_search_st</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_url_search_st</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_url_search_st</function></primary>
</indexterm>
<para>The <function>ldap_url_search_st</function> function searches the directory,
synchronously within a specified time limit, for matching entries, based on
the contents of the URL.</para>
<sect3 id="gasek"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
     struct timeval *timeout, LDAPMessage **res );</programlisting>
</sect3>
<sect3 id="gasfe"><title>Parameters</title>
<table frame="topbot" id="gasgb"><title><function>ldap_url_search_st</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>url</literal></para></entry>
<entry>
<para>LDAP URL specifying a search of the directory.</para></entry>
</row>
<row>
<entry>
<para><literal>attrsonly</literal></para></entry>
<entry>
<para>Specifies whether or not attribute values are returned along with the
attribute types. This parameter can have the following values:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that both attribute types and
attribute values are returned.</para></listitem>
<listitem><para><literal>1</literal> specifies that only attribute types are
returned.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>timeout</literal></para></entry>
<entry>
<para>Maximum time to wait for the results of the search.</para></entry>
</row>
<row>
<entry>
<para><literal>res</literal></para></entry>
<entry>
<para>Results of the search (when the call is completed).</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasey"><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
when receiving the results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
when decoding the BER-encoded results from the server.</para></listitem>
<listitem><para><errorcode>LDAP_FILTER_ERROR</errorcode> if an error occurred
when parsing and BER-encoding the search filter specified by the filter argument.
</para></listitem>
<listitem><para><errorcode>LDAP_TIMEOUT</errorcode> if the search exceeded
the time specified by the <literal>timeoutp</literal> argument.</para>
</listitem>
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
included in your request (for example, as a session preference) and your LDAP
client does not specify that it is using the LDAP v3. Make sure that you set
the version of your LDAP client to version 3 before calling this function.</para>
</listitem>
</itemizedlist>
<note><para>&cnDirectoryServer; and other LDAP server products may send result
codes in addition to those described. For example, the server may have loaded
a plug-in that returns custom result codes. Check your LDAP server documentation
for other result codes.</para></note>
</sect3>
<sect3 id="gasfq"><title>Description</title>
<para>The <function>ldap_url_search_st</function> function searches the directory
for matching entries, based on the contents of the URL. This function works
like <olink targetptr="bdawn">ldap_url_search_s</olink> and lets you specify
a time out period for the search.</para></sect3>
<sect3 id="gasfs"><title>See Also</title>
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavb">ldap_search_s
</olink></para></sect3>
</sect2>
<sect2 id="bdawp"><title><function>ldap_utf8characters</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8characters</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8characters</function></primary>
</indexterm>
<para>The <function>ldap_utf8characters</function> function accepts a Unicode
string and returns the number of characters.</para>
<sect3 id="gaseo"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 size_t ldap_utf8characters( const char* );</programlisting>
</sect3>
<sect3 id="gasen"><title>Parameters</title>
<table frame="topbot" id="gasgc"><title><function>ldap_utf8characters</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>char</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 string.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasev"><title>Returns</title>
<para>Returns the number of UTF-8 characters in the <literal>0</literal> terminated
array.</para></sect3>
</sect2>
<sect2 id="bdawq"><title><function>ldap_utf8copy</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8copy</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8copy</function></primary>
</indexterm>
<para>The <function>ldap_utf8copy</function> function accepts a Unicode string
and copies the characters to a destination.</para>
<sect3 id="gases"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8copy( char* dst, const char* src );</programlisting>
</sect3>
<sect3 id="gasfx"><title>Parameters</title>
<table frame="topbot" id="gasgd"><title><function>ldap_utf8copy</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>dst</literal></para></entry>
<entry>
<para>Pointer to a destination for the copied characters.</para></entry>
</row>
<row>
<entry>
<para><literal>src</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 string to copy.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasfh"><title>Description</title>
<para><function>ldap_utf8copy</function> copies a character from <literal>src</literal> to
 <literal>dst</literal>. This function handles any valid UTF-8 character (including
 <literal>\0</literal> and ASCII).</para></sect3>
<sect3 id="gasfn"><title>Returns</title>
<para>The number of characters copied.</para></sect3>
</sect2>
<sect2 id="bdawr"><title><function>ldap_utf8getcc</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8getcc</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8getcc</function></primary>
</indexterm>
<para>The <function>ldap_utf8getcc</function> function gets one UCS-4 character
and moves the pointer to the next character.</para>
<sect3 id="gasfu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 unsigned long ldap_utf8getcc( const char** src );</programlisting>
</sect3>
<sect3 id="gasfr"><title>Parameters</title>
<table frame="topbot" id="gashv"><title><function>ldap_utf8getcc</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>src</literal></para></entry>
<entry>
<para>Pointer to a UCS-4 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdaws"><title><function>ldap_utf8isalnum</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8isalnum</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8isalnum</function></primary>
</indexterm>
<para>The <function>ldap_utf8isalnum</function> function determines whether
the character is an alphanumeric one.</para>
<sect3 id="gasgw"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8isalnum( char* s );</programlisting>
</sect3>
<sect3 id="gashi"><title>Parameters</title>
<table frame="topbot" id="gasgs"><title><function>ldap_utf8isalnum</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawt"><title><function>ldap_utf8isalpha</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8isalpha</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8isalpha</function></primary>
</indexterm>
<para>The <function>ldap_utf8isalpha</function> function determines whether
the character is a letter.</para>
<sect3 id="gasgi"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8isalpha( char* s );</programlisting>
</sect3>
<sect3 id="gashl"><title>Parameters</title>
<table frame="topbot" id="gasgl"><title><function>ldap_utf8isalpha</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawu"><title><function>ldap_utf8isdigit</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8isdigit</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8isdigit</function></primary>
</indexterm>
<para>The <function>ldap_utf8isdigit</function> function determines whether
the character is a number.</para>
<sect3 id="gasgu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8isdigit( char* s );</programlisting>
</sect3>
<sect3 id="gashp"><title>Parameters</title>
<table frame="topbot" id="gasgv"><title><function>ldap_utf8isdigit</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawv"><title><function>ldap_utf8isspace</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8isspace</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8isspace</function></primary>
</indexterm>
<para>The <function>ldap_utf8isspace</function> function determines whether
the character is a space, tab, newline, return or formfeed.</para>
<sect3 id="gasgj"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8isspace( char* s );</programlisting>
</sect3>
<sect3 id="gasgq"><title>Parameters</title>
<table frame="topbot" id="gashj"><title><function>ldap_utf8isspace</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>s</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdaww"><title><function>ldap_utf8len</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8len</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8len</function></primary>
</indexterm>
<para>The <function>ldap_utf8len</function> function accepts a Unicode string
and returns the number of bytes it contains.</para>
<sect3 id="gashf"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 int ldap_utf8len( const char* );</programlisting>
</sect3>
<sect3 id="gashr"><title>Parameters</title>
<table frame="topbot" id="gashs"><title><function>ldap_utf8len</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>char</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 string.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawx"><title><function>ldap_utf8next</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8next</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8next</function></primary>
</indexterm>
<para>The <function>ldap_utf8next</function> function accepts a character
and returns a pointer to the character immediately following it.</para>
<sect3 id="gashq"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char* ldap_utf8next( char* );</programlisting>
</sect3>
<sect3 id="gasgk"><title>Parameters</title>
<table frame="topbot" id="gasht"><title><function>ldap_utf8next</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>char</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawy"><title><function>ldap_utf8prev</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8prev</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8prev</function></primary>
</indexterm>
<para>The <function>ldap_utf8prev</function> function accepts a character
and returns a pointer to the previous character.</para>
<sect3 id="gashg"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char* ldap_utf8prev( char* );</programlisting>
</sect3>
<sect3 id="gasgn"><title>Parameters</title>
<table frame="topbot" id="gashn"><title><function>ldap_utf8prev</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>char</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 character.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdawz"><title><function>ldap_utf8strtok_r</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_utf8strtok_r</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_utf8strtok_r</function></primary>
</indexterm>
<para>The <function>ldap_utf8strtok_r</function> function gets the next token
from a string.</para>
<sect3 id="gashd"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 char* ldap_utf8strtok_r( char* src, const char* brk, char** next);</programlisting>
</sect3>
<sect3 id="gasha"><title>Parameters</title>
<table frame="topbot" id="gashw"><title><function>ldap_utf8strtok_r</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>src</literal></para></entry>
<entry>
<para>Pointer to a UTF-8 string from which to extract token.</para></entry>
</row>
<row>
<entry>
<para><literal>brk</literal></para></entry>
<entry>
<para>Points to a <literal>NULL</literal> terminated set of delimiter characters.
</para></entry>
</row>
<row>
<entry>
<para><literal>next</literal></para></entry>
<entry>
<para>Pointer to the next token.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gashm"><title>Returns</title>
<para>Returns a pointer to the next token. If there are no remaining tokens,
returns a <literal>NULL</literal> pointer.</para></sect3>
</sect2>
<sect2 id="ldap-whoami"><title><function>ldap_whoami</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_whoami</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_whoami</function></primary>
</indexterm>
<para>The <function>ldap_whoami</function> function sends an asynchronous
Who am I? extended operation request to determine the authorization identity
associated with a connection.</para>
<sect3><title>Syntax</title>
<programlisting>LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls,
    LDAPControl **clientctrls, int *msgidp );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgpi"><title><function>ldap_whoami</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><parameter>msgidp</parameter></para></entry>
<entry>
<para>Pointer to the message ID for this asynchronous call, for use with <olink targetptr="ldap-parse-whoami-result">ldap_parse_whoami_result</olink>, or
to retrieve the result for use with <olink targetptr="ldap-parse-whoami">ldap_parse_whoami
</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="ldap-whoami-s"><title><function>ldap_whoami_s</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_whoami_s</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_whoami_s</function></primary>
</indexterm>
<para>The <function>ldap_whoami_s</function> function sends a synchronous
Who am I? extended operation request to determine the authorization identity
associated with a connection.</para>
<sect3><title>Syntax</title>
<programlisting>LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls,
    LDAPControl **clientctrls, char **authzid );</programlisting>
</sect3>
<sect3><title>Parameters</title>
<table frame="topbot" id="gbgpia"><title><function>ldap_whoami_s</function> Function
Parameters</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
information about the connection to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><literal>serverctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP server controls that apply to this operation. If you do
not want to pass any server controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><literal>clientctrls</literal></para></entry>
<entry>
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
representing LDAP client controls that apply to this operation. If you do
not want to pass any client controls, specify <literal>NULL</literal> for
this argument.</para></entry>
</row>
<row>
<entry>
<para><parameter>authzid</parameter></para></entry>
<entry>
<para>Pointer to the string to hold the authorization identity retrieved from
the server.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Returns</title>
<para>One of the following values:</para>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
are invalid.</para></listitem>
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
when BER-encoding the request.</para></listitem>
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
did not receive the request or if the connection to the server was lost.</para>
</listitem>
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
allocated.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdaxa"><title><function>ldap_vals2html</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_vals2html</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_vals2html</function></primary>
</indexterm>
<para>The <function>ldap_vals2html</function> function writes the HTML representation
of a set of values.</para>
<sect3 id="gasgp"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_vals2html( LDAP *ld, char *buf, char **vals, char *label,
    int labelwidth, unsigned long syntaxid, writeptype writeproc,
    void *writeparm, char *eol, int rdncount, char *urlprefix );</programlisting>
</sect3>
<sect3 id="gasgr"><title>Parameters</title>
<table frame="topbot" id="gashc"><title><function>ldap_vals2html</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The LDAP pointer obtained by a previous call to <olink targetptr="bdauj">ldap_open
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>buf</literal></para></entry>
<entry></entry>
</row>
<row>
<entry>
<para><literal>vals</literal></para></entry>
<entry>
<para>A NULL terminated list of values, usually obtained by a call to  <olink targetptr="bdast">ldap_get_values</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>label</literal></para></entry>
<entry>
<para>A string (usually a friendly form of an LDAP attribute name) shown next
to the values.</para></entry>
</row>
<row>
<entry>
<para><literal>labelwidth</literal></para></entry>
<entry>
<para>Specifies the label margin (the number of blank spaces displayed to
the left of the values). If zero is passed, a default label width is used.</para>
</entry>
</row>
<row>
<entry>
<para><literal>syntaxid</literal></para></entry>
<entry>
<para>Display template attribute syntax identifier for a list of predefined <literal>
LDAP_SYN_...</literal> values.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para><function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
<row>
<entry>
<para><literal>urlprefix</literal></para></entry>
<entry>
<para>Starting text to use  when constructing  an LDAP URL. The  default 
is  the  string <literal>ldap://</literal></para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gashe"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasgz"><title>Description</title>
<para><function>ldap_vals2html</function> produces HTML output of a single
set of LDAP attribute values.</para></sect3>
<sect3 id="gasgm"><title>See Also</title>
<para><olink targetptr="bdaxb">ldap_vals2text</olink></para></sect3>
</sect2>
<sect2 id="bdaxb"><title><function>ldap_vals2text</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_vals2text</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_vals2text</function></primary>
</indexterm>
<para>The <function>ldap_vals2text</function> function writes the text representation
of an LDAP entry.</para>
<sect3 id="gasgt"><title>Syntax</title>
<programlisting>#include &lt;disptmpl.h>
 int ldap_vals2text( LDAP *ld, char *buf, char **vals, char *label,
    int labelwidth, unsigned long syntaxid, writeptype writeproc,
    void *writeparm, char *eol, int rdncount );</programlisting>
</sect3>
<sect3 id="gashb"><title>Parameters</title>
<table frame="topbot" id="gasgx"><title><function>ldap_vals2text</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The LDAP pointer obtained by a previous call to <olink targetptr="bdauj">ldap_open
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>buf</literal></para></entry>
<entry></entry>
</row>
<row>
<entry>
<para><literal>vals</literal></para></entry>
<entry>
<para>A <literal>NULL</literal> terminated list of values, usually obtained
by a call to  <olink targetptr="bdast">ldap_get_values</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>label</literal></para></entry>
<entry>
<para>A string (usually a friendly form of an LDAP attribute name) shown next
to the values.</para></entry>
</row>
<row>
<entry>
<para><literal>labelwidth</literal></para></entry>
<entry>
<para>Specifies the label margin (the number of blank spaces displayed to
the left of the values). If zero is passed, a default label width is used.</para>
</entry>
</row>
<row>
<entry>
<para><literal>syntaxid</literal></para></entry>
<entry>
<para>Display template attribute syntax identifier for a list of predefined <literal>
LDAP_SYN_...</literal> values.</para></entry>
</row>
<row>
<entry>
<para><literal>writeproc</literal></para></entry>
<entry>
<para><function>writeproc</function> function should be declared as:</para>
<para><literal>int writeproc( writeparm, p, len )</literal></para>
<para><literal>void  *writeparm;</literal></para>
<para><literal>char  *p;</literal></para>
<para><literal>int  len;</literal></para>
<para>where <literal>p</literal> is a pointer to text to be written and  <literal>
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
to be zero terminated.</para></entry>
</row>
<row>
<entry>
<para><literal>writeparm</literal></para></entry>
<entry>
<para>A pointer to a structure that will be passed as the first parameter
of the <function>writeproc</function> procedure. Typically, this is used to
pass the file descriptor of the file to write to.</para></entry>
</row>
<row>
<entry>
<para><literal>eol</literal></para></entry>
<entry>
<para>Lines of text are terminated with this string.</para></entry>
</row>
<row>
<entry>
<para><literal>rdncount</literal></para></entry>
<entry>
<para>Limits the number of components that are displayed for DN attributes.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasho"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP error code on error.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gashk"><title>Description</title>
<para><function>ldap_vals2text</function> produces a text representation of
a single set of LDAP attribute values.</para></sect3>
<sect3 id="gasgo"><title>See Also</title>
<para><olink targetptr="bdaxa">ldap_vals2html</olink></para></sect3>
</sect2>
<sect2 id="bdaxc"><title><function>ldap_value_free</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_value_free</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_value_free</function></primary>
</indexterm>
<para>The <function>ldap_value_free</function> function frees an array of
values from memory.</para>
<sect3 id="gashu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_value_free( char **values );</programlisting>
</sect3>
<sect3 id="gasgy"><title>Parameters</title>
<table frame="topbot" id="gashh"><title><function>ldap_value_free</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>values</literal></para></entry>
<entry>
<para>Array of values.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasin"><title>Description</title>
<para>Use the <olink targetptr="bdaxd">ldap_value_free_len</olink> function
if the values are <olink targetptr="bdakg">berval</olink> structures.</para>
</sect3>
<sect3 id="gasir"><title>Example</title>
<para>See the example under <olink targetptr="bdast">ldap_get_values</olink>.</para>
</sect3>
<sect3 id="gashz"><title>See Also</title>
<para><olink targetptr="bdast">ldap_get_values</olink>,  <olink targetptr="bdaxd">
ldap_value_free_len</olink></para></sect3>
</sect2>
<sect2 id="bdaxd"><title><function>ldap_value_free_len</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_value_free_len</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_value_free_len</function></primary>
</indexterm>
<para>The <function>ldap_value_free_len</function> function frees an array
of <olink targetptr="bdakg">berval</olink> structures from memory.</para>
<sect3 id="gasjg"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
 void ldap_value_free_len( struct berval **values );</programlisting>
</sect3>
<sect3 id="gasip"><title>Parameters</title>
<table frame="topbot" id="gasjc"><title><function>ldap_value_free_len</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>values</literal></para></entry>
<entry>
<para>Array of <structname>berval</structname> structures.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasjj"><title>Description</title>
<para>Use the <olink targetptr="bdaxc">ldap_value_free</olink> function instead
of this function if the values are string values.</para></sect3>
<sect3 id="gasjq"><title>Example</title>
<para>See the example under <olink targetptr="bdasu">ldap_get_values_len</olink>.
</para></sect3>
<sect3 id="gasid"><title>See Also</title>
<para><olink targetptr="bdast">ldap_get_values</olink>,  <olink targetptr="bdasu">
ldap_get_values_len</olink></para></sect3>
</sect2>
<sect2 id="bdaxe"><title><function>ldap_version</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_version</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_version</function></primary>
</indexterm>
<note><para>This function is deprecated and should not be used. It is included
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
use <olink targetptr="bdass">ldap_get_option</olink> with <literal>LDAP_OPT_API_INFO
</literal> and an <literal>LDAPAPIInfo</literal> structure.</para></note>
<para>The <function>ldap_version</function> function gets version information
about the &DirectorySDKForC; libraries.</para>
<sect3 id="gasiu"><title>Syntax</title>
<programlisting>#include &lt;ldap.h>
int ldap_version( LDAPVersion *ver );</programlisting>
</sect3>
<sect3 id="gasio"><title>Parameters</title>
<table frame="topbot" id="gasjr"><title><function>ldap_version</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ver</literal></para></entry>
<entry>
<para><olink targetptr="bdamu">LDAPVersion</olink> structure returning version
information. If you only want the SDK version, you can pass <literal>NULL</literal> for
this parameter.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasik"><title>Returns</title>
<para>The version number of the &DirectorySDKForC;, multiplied by 100.
For example, for version 1.0, the function returns 100.</para></sect3>
<sect3 id="gasiw"><title>See Also</title>
<para><olink targetptr="bdass">ldap_get_option</olink></para></sect3>
</sect2>
<sect2 id="bdaxf"><title><function>ldap_x_calloc</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>ldap_x_*</function></secondary>
</indexterm><indexterm>
<primary><function>ldap_x_*</function></primary>
</indexterm>
<para>The <function>ldap_x_calloc</function> function allocates space for
an array of elements.</para>
<sect3 id="gasib"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
void *ldap_x_calloc( size_t nelem, size_t elsize );</programlisting>
</sect3>
<sect3 id="gasji"><title>Parameters</title>
<table frame="topbot" id="gasjk"><title><function>ldap_x_calloc</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>nelem</literal></para></entry>
<entry>
<para>Number of elements for which memory is to be allocated.</para></entry>
</row>
<row>
<entry>
<para><literal>elsize</literal></para></entry>
<entry>
<para>Size of each element.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasiy"><title>Returns</title>
<itemizedlist>
<listitem><para>If successful, returns a pointer to the space.</para></listitem>
<listitem><para>If there is no available memory, returns a <literal>NULL</literal> pointer.
</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasic"><title>See Also</title>
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxl">ldap_x_malloc
</olink> , <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
</sect2>
<sect2 id="bdaxg"><title><function>ldap_x_free</function></title>
<para>The <function>ldap_x_free</function> function frees allocated memory.</para>
<sect3 id="gasif"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
void ldap_x_free( void *ptr );</programlisting>
</sect3>
<sect3 id="gasjo"><title>Parameters</title>
<table frame="topbot" id="gasjh"><title><function>ldap_x_free</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ptr</literal></para></entry>
<entry>
<para>Pointer to the block of memory to be freed.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasiz"><title>See Also</title>
<para><olink targetptr="bdaxf">ldap_x_calloc</olink>,  <olink targetptr="bdaxl">ldap_x_malloc
</olink>, <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
</sect2>
<sect2 id="bdaxh"><title><function>ldap_x_hostlist_first</function></title>
<para>The <function>ldap_x_hostlist_first</function> function returns the
first host and port defined in a host list file.</para>
<sect3 id="gasii"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
 int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp,
     int *portp, struct ldap_x_hostlist_status **statusp );</programlisting>
</sect3>
<sect3 id="gasim"><title>Description</title>
<para><function>ldap_x_hostlist_first</function> parses a space-separated
host list (useful for implementing an extended I/O CONNECT callback function)
and returns the first host and port defined.</para></sect3>
<sect3 id="gashx"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>If unsuccessful returns a valid LDAP API error code.</para>
</listitem>
</itemizedlist>
<note><para>A <literal>NULL</literal> or zero-length <parameter>hostlist</parameter> causes
the host  <literal>127.0.0.1</literal> to be returned.</para></note>
</sect3>
<sect3 id="gasjm"><title>See Also</title>
<para><olink targetptr="bdanc">ldap_x_hostlist_status</olink>,  <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK</olink>,</para></sect3>
</sect2>
<sect2 id="bdaxi"><title><function>ldap_x_hostlist_next</function></title>
<para>The <function>ldap_x_hostlist_next</function> function returns the host
and port defined in a host list file following the previous host and port
returned.</para>
<sect3 id="gasia"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
 int ldap_x_hostlist_next( char **hostp, int *portp,
    struct ldap_x_hostlist_status **statusp );</programlisting>
</sect3>
<sect3 id="gasju"><title>Description</title>
<para>This utility parses a space-separated host list (useful for implementing
an extended I/O CONNECT callback function) and returns the host and port defined
following the previous host and port returned.</para></sect3>
<sect3 id="gasix"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful. If no more
hosts are available, <literal>LDAP_SUCCESS</literal> is returned but <literal>hostp
</literal> is set to <literal>NULL</literal>.</para></listitem>
<listitem><para>If unsuccessful returns a valid LDAP API error code.</para>
</listitem>
</itemizedlist>
<note><para>A <literal>NULL</literal> or zero-length <parameter>hostlist</parameter> causes
the host  <literal>127.0.0.1</literal> to be returned.</para></note>
</sect3>
<sect3 id="gasiq"><title>See Also</title>
<para><olink targetptr="bdanc">ldap_x_hostlist_status</olink>,  <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK</olink>,</para></sect3>
</sect2>
<sect2 id="bdaxj"><title><function>ldap_x_hostlist_status</function></title>
<sect3 id="gasie"><title>See Also</title>
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>,  <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink></para></sect3>
</sect2>
<sect2 id="bdaxk"><title><function>ldap_x_hostlist_statusfree</function></title>
<sect3 id="gasjw"><title>See Also</title>
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>,  <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink></para></sect3>
</sect2>
<sect2 id="bdaxl"><title><function>ldap_x_malloc</function></title>
<para>The <function>ldap_x_malloc</function> function allocates space for
an object.</para>
<sect3 id="gasjf"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
void *ldap_x_malloc( size_t size );</programlisting>
</sect3>
<sect3 id="gasij"><title>Parameters</title>
<table frame="topbot" id="gashy"><title><function>ldap_x_malloc</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>size</literal></para></entry>
<entry>
<para>Specifies the size for the allocated block of memory.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasil"><title>See Also</title>
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxf">ldap_x_calloc
</olink> , <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
</sect2>
<sect2 id="bdaxm"><title><function>ldap_x_realloc</function></title>
<para>The <function>ldap_x_realloc</function> function changes the size of
a block of memory.</para>
<sect3 id="gasih"><title>Syntax</title>
<programlisting>#include &lt;ldap-extension.h>
void *ldap_x_realloc( void *ptr, size_t size );</programlisting>
</sect3>
<sect3 id="gasjb"><title>Parameters</title>
<table frame="topbot" id="gasjl"><title><function>ldap_x_realloc</function> Function
Parameter</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ptr</literal></para></entry>
<entry>
<para>Pointer to a block of memory.</para></entry>
</row>
<row>
<entry>
<para><literal>size</literal></para></entry>
<entry>
<para>Specifies the new size of the block.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasiv"><title>See Also</title>
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxf">ldap_x_calloc
</olink> , <olink targetptr="bdaxl">ldap_x_malloc</olink></para></sect3>
</sect2>
<sect2 id="bdaxn"><title><function>prldap_get_default_socket_info</function></title>
<indexterm>
<primary>C SDK functions</primary>
<secondary><function>prldap_*</function></secondary>
</indexterm><indexterm>
<primary><function>prldap_*</function></primary>
</indexterm>
<para>The <function>prldap_get_default_socket_info</function> function retrieves
default socket information.</para>
<sect3 id="gasig"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</programlisting>
</sect3>
<sect3 id="gasjn"><title>Parameters</title>
<table frame="topbot" id="gasjt"><title><function>prldap_get_default_socket_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>fd</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>soip</literal></para></entry>
<entry>
<para>Pointer to a structure containing socket specific information.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasjs"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> is returned if <literal>ld
</literal>  is <literal>NULL</literal>.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasit"><title>See Also</title>
<para><olink targetptr="bdaxt">prldap_set_default_socket_info</olink></para>
</sect3>
</sect2>
<sect2 id="bdaxo"><title><function>prldap_get_session_info</function></title>
<para>The <function>prldap_get_session_info</function> function retrieves
application-specific data.</para>
<sect3 id="gasis"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_get_session_info( LDAP *ld, void *sessionarg,
    PRLDAPSessionInfo *seip );</programlisting>
</sect3>
<sect3 id="gasja"><title>Parameters</title>
<table frame="topbot" id="gasjd"><title><function>prldap_get_session_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
If <literal>NULL</literal>, the functions are installed as the default functions
for all new LDAP handles.</para></entry>
</row>
<row>
<entry>
<para><literal>seip</literal></para></entry>
<entry>
<para>Pointer to a structure with session information data.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasjp"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasje"><title>Description</title>
<para>The <function>prldap_get_session_option</function> function retrieves
an option for an LDAP session handle or a session argument that is passed
to the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
or <literal>DISPOSEHANDLE</literal>  extended I/O callbacks.</para></sect3>
<sect3 id="gasjv"><title>See Also</title>
<para><olink targetptr="bdaxu">prldap_set_session_info</olink></para></sect3>
</sect2>
<sect2 id="bdaxp"><title><function>prldap_get_session_option</function></title>
<para>The <function>prldap_get_session_option</function> function retrieves
an option specific to the <literal>prldap</literal> layer.</para>
<sect3 id="gasla"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_get_session_option( LDAP *ld, void *sessionarg,
    int option, ... );</programlisting>
</sect3>
<sect3 id="gasll"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaskn"><title>Description</title>
<para>The <function>prldap_get_session_option</function> function retrieves
an option for an LDAP session handle or a session argument that is passed
to the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
or <literal>DISPOSEHANDLE</literal>  extended I/O callbacks.</para></sect3>
<sect3 id="gaslm"><title>See Also</title>
<para><olink targetptr="bdaxv">prldap_set_session_option</olink></para></sect3>
</sect2>
<sect2 id="bdaxq"><title><function>prldap_get_socket_info</function></title>
<para>The <function>prldap_get_socket_info</function> function retrieves socket-specific
information based on parameters passed to the extended I/O callback functions.</para>
<sect3 id="gaskd"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_get_socket_info( int fd, void *socketarg,
    PRLDAPSocketInfo *soip );</programlisting>
</sect3>
<sect3 id="gasle"><title>Parameters</title>
<table frame="topbot" id="gasjy"><title><function>prldap_get_socket_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>fd</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>soip</literal></para></entry>
<entry>
<para>Pointer to a structure containing socket information data.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaskr"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaskw"><title>See Also</title>
<para><olink targetptr="bdaxw">prldap_set_socket_info</olink></para></sect3>
</sect2>
<sect2 id="bdaxr"><title><function>prldap_init</function></title>
<para>The <function>prldap_init</function> function creates a new session
handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6,
and DNS functions installed.</para>
<sect3 id="gasli"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 LDAP * prldap_init( const char *defhost, int defport, int shared );</programlisting>
</sect3>
<sect3 id="gaskp"><title>Parameters</title>
<table frame="topbot" id="gaskh"><title><function>prldap_init</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>defhost</literal></para></entry>
<entry>
<para>Space-delimited list of one or more host names (or IP address in dotted
notation, such as <literal>192.168.0.99</literal>) of the LDAP servers that
you want the LDAP client to connect to. The names can be in <replaceable>hostname
</replaceable>: <replaceable>portnumber</replaceable> format (in which case, <replaceable>
portnumber</replaceable> overrides the port number specified by the <parameter>defport
</parameter> argument.</para></entry>
</row>
<row>
<entry>
<para><literal>defport</literal></para></entry>
<entry>
<para>Default port number of the LDAP server. To specify the standard LDAP
port (port 389), use <literal>LDAP_PORT</literal> as the value for this parameter.
</para></entry>
</row>
<row>
<entry>
<para><literal>shared</literal></para></entry>
<entry>
<para>Pass a non-zero value if you plan to use this LDAP handle for more than
one thread.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaslb"><title>Returns</title>
<itemizedlist>
<listitem><para>Pointer to LDAP session handle if successful.</para></listitem>
<listitem><para><literal>NULL</literal> if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaskx"><title>Description</title>
<para>To be able to use LDAP over Internet Protocol, version 6, <acronym>IPv6</acronym>,
this function should be used rather than <olink targetptr="bdasv">ldap_init</olink>.
</para></sect3>
<sect3 id="gaslf"><title>See Also</title>
<para><olink targetptr="bdaxs">prldap_install_routines</olink></para></sect3>
</sect2>
<sect2 id="bdaxs"><title><function>prldap_install_routines</function></title>
<para>The <function>prldap_install_routines</function> function installs Netscape
Portable Runtime (NSPR) I/O, threading, and DNS functions so they can be used
by the LDAP session handle.</para>
<sect3 id="gaslh"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_install_routines( LDAP *ld, int shared );</programlisting>
</sect3>
<sect3 id="gaskb"><title>Parameters</title>
<table frame="topbot" id="gaske"><title><function>prldap_install_routines</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
If <literal>NULL</literal>, the functions are installed as the default functions
for all new LDAP handles.</para></entry>
</row>
<row>
<entry>
<para><literal>shared</literal></para></entry>
<entry>
<para>Pass a non-zero value if you plan to use this LDAP handle for more than
one thread.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasko"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaska"><title>See Also</title>
<para><olink targetptr="bdaxr">prldap_init</olink></para></sect3>
</sect2>
<sect2 id="bdaxt"><title><function>prldap_set_default_socket_info</function></title>
<para>The <function>prldap_set_default_socket_info</function> function sets
default socket information.</para>
<sect3 id="gaslc"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</programlisting>
</sect3>
<sect3 id="gaskq"><title>Parameters</title>
<table frame="topbot" id="gasku"><title><function>prldap_set_default_socket_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>fd</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>soip</literal></para></entry>
<entry>
<para>Pointer to a structure containing socket specific information.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaskv"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> is returned if <literal>ld
</literal>  is <literal>NULL</literal>.</para></listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaslj"><title>See Also</title>
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></sect3>
</sect2>
<sect2 id="bdaxu"><title><function>prldap_set_session_info</function></title>
<para>The <function>prldap_set_session_info</function> function sets application-specific
data.</para>
<sect3 id="gaslk"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_set_session_info( LDAP *ld, void *sessionarg,
    PRLDAPSessionInfo *seip );</programlisting>
</sect3>
<sect3 id="gaslg"><title>Parameters</title>
<table frame="topbot" id="gaskz"><title><function>prldap_set_session_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>seip</literal></para></entry>
<entry>
<para>Pointer to a structure containing session information data.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaskm"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaskt"><title>Description</title>
<para>The <function>prldap_set_session_info</function> function sets application-specific
data for an LDAP session handle or a session argument that is passed to the
 <literal>CONNECT</literal>, <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
or  <literal>DISPOSEHANDLE</literal> extended I/O callbacks.</para></sect3>
<sect3 id="gaskj"><title>See Also</title>
<para><olink targetptr="bdaxo">prldap_get_session_info</olink></para></sect3>
</sect2>
<sect2 id="bdaxv"><title><function>prldap_set_session_option</function></title>
<para>The <function>prldap_set_session_option</function> function sets a session
option specific to the <literal>prldap</literal> layer.</para>
<sect3 id="gasjx"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_set_session_option( LDAP *ld, void *sessionarg,
    int option, ... );</programlisting>
</sect3>
<sect3 id="gasjz"><title>Parameters</title>
<table frame="topbot" id="gasld"><title><function>prldap_set_session_option</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ld</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>option</literal></para></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaskc"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gaskf"><title>Description</title>
<para>The <function>prldap_set_session_option</function> function sets an
option for an LDAP session handle or a session argument that is passed to
the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
or <literal>DISPOSEHANDLE</literal>  extended I/O callbacks.</para></sect3>
<sect3 id="gaskl"><title>See Also</title>
<para><olink targetptr="bdaxp">prldap_get_session_option</olink></para></sect3>
</sect2>
<sect2 id="bdaxw"><title><function>prldap_set_socket_info</function></title>
<para>The <function>prldap_set_socket_info</function> function sets socket
information.</para>
<sect3 id="gaskg"><title>Syntax</title>
<programlisting>#include &lt;ldappr.h>
 int prldap_set_socket_info( int fd, void *socketarg,
    PRLDAPSocketInfo *soip );</programlisting>
</sect3>
<sect3 id="gasks"><title>Parameters</title>
<table frame="topbot" id="gaski"><title><function>prldap_set_socket_info</function> Function
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>fd</literal></para></entry>
<entry>
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
</para></entry>
</row>
<row>
<entry>
<para><literal>soip</literal></para></entry>
<entry>
<para>Pointer to a structure containing socket information data.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gaskk"><title>Returns</title>
<itemizedlist>
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
</listitem>
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
</itemizedlist>
</sect3>
<sect3 id="gasky"><title>Description</title>
<para>The <function>prldap_set_socket_info</function> function sets socket-specific
information based on parameters passed to the extended I/O callback functions.
For more information, see the <literal>ldappr.h</literal> header file.</para>
</sect3>
<sect3 id="gasnf"><title>See Also</title>
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></sect3>
</sect2>
</sect1>
</chapter>
