X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Fldap.3;h=f0f799abe27ff385a85ac29cef9444a521b6f515;hb=473e2c997f6b1f226d35da186db8033c922001f3;hp=f65fc1d3a9923c231380c955d6d7e333e1c19f34;hpb=b17f72ef8ae92f65c1ff1c3b21b2ff280f4880a5;p=openldap

diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3
index f65fc1d3a9..f0f799abe2 100644
--- a/doc/man/man3/ldap.3
+++ b/doc/man/man3/ldap.3
@@ -1,9 +1,11 @@
-.TH LDAP 3 "13 January 2002" "OpenLDAP LDVERSION"
+.TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
-.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ldap - OpenLDAP Lightweight Directory Access Protocol API
+ldap \- OpenLDAP Lightweight Directory Access Protocol API
+.SH LIBRARY
+OpenLDAP LDAP (libldap, \-lldap)
 .SH SYNOPSIS
 .nf
 .ft B
@@ -12,13 +14,14 @@ ldap - OpenLDAP Lightweight Directory Access Protocol API
 .fi
 .SH DESCRIPTION
 .LP
-The Lightweight Directory Access Protocol provides access to X.500
-directory services.  The services may be stand\-alone or part of
-a distributed directory service.  This API supports LDAP over TCP
-(RFC2251), LDAP over SSL, and LDAP over IPC (UNIX domain sockets).
-This API supports SASL (RFC2829) and Start TLS (RFC2830).  This
-API is based upon IETF C LDAP API draft specification, a work in
-progress.
+The Lightweight Directory Access Protocol (LDAP) (RFC 4510) provides
+access to X.500 directory services.  These services may be stand\-alone
+or part of a distributed directory service.  This client API supports
+LDAP over TCP (RFC 4511), LDAP over TLS/SSL, and LDAP over IPC (UNIX
+domain sockets).  This API supports SASL (RFC 4513) and Start TLS
+(RFC 4513) as well as a number of protocol extensions.  This API is
+loosely based upon IETF/LDAPEXT C LDAP API draft specification, a (orphaned)
+work in progress.
 .LP
 The OpenLDAP Software package includes a stand\-alone server in
 .BR slapd (8),
@@ -32,21 +35,25 @@ These routines are found in the \-lldap library.
 .LP
 The basic interaction is as follows.  A session handle is
 created using
-.BR ldap_init (3)
-or
-.BR ldap_initialize (3).
-(The
 .BR ldap_initialize (3)
-routine is preferred, but is not part of the draft specification.)
-The underlying session is established upon first use which is
-commonly an LDAP bind operation.  The LDAP bind operation is
-performed by calling
+and set the protocol version to 3 by calling
+.BR ldap_set_option (3).
+The underlying session is established first operation is
+issued.  This would generally be a Start TLS or Bind operation,
+or a Search operation to read attributes of the Root DSE.
+A Start TLS operation is performed by calling
+.BR ldap_start_tls_s (3).
+A LDAP bind operation is performed by calling
 .BR ldap_sasl_bind (3)
-or one of its friends.  Next, other operations are performed
+or one of its friends.
+A Search operation is performed by calling ldap_search_ext_s(3)
+or one of its friends.
+
+Subsequently, additional operations are performed
 by calling one of the synchronous or asynchronous routines (e.g.,
-.BR ldap_search_ext_s (3)
+.BR ldap_compare_ext_s (3)
 or
-.BR ldap_search_ext (3)
+.BR ldap_compare_ext (3)
 followed by
 .BR ldap_result (3)).
 Results returned from these routines are interpreted by calling the
@@ -56,11 +63,41 @@ The LDAP association and underlying connection is terminated by calling
 .BR ldap_unbind_ext (3).
 Errors can be interpreted by calling
 .BR ldap_err2string (3).
-.SH SEARCH FILTERS
-Search filters to be passed to the ldap search routines are to be
-constructed by hand and should conform to RFC 2254.
+.SH LDAP versions
+This library supports version 3 of the Lightweight Directory Access
+Protocol (LDAPv3) as defined in RFC 4510.  It also supports a variant
+of version 2 of LDAP as defined by U-Mich LDAP and, to some degree,
+RFC 1777.  Version 2 (all variants) are considered obsolete.
+Version 3 should be used instead.
+.LP
+For backwards compatibility reasons, the library defaults to version 2.
+Hence, all new applications (and all actively maintained applications)
+should use
+.BR ldap_set_option (3)
+to select version 3.  The library manual pages assume version 3
+has been selected.
+.SH INPUT and OUTPUT PARAMETERS
+All character string input/output is expected to be/is UTF-8
+encoded Unicode (version 3.2). 
+.LP
+Distinguished names (DN) (and relative distinguished names (RDN) to
+be passed to the LDAP routines should conform to RFC 4514 UTF-8
+string representation. 
+.LP
+Search filters to be passed to the search routines are to be
+constructed by hand and should conform to RFC 4515 UTF-8
+string representation.
+.LP
+LDAP URLs to be passed to routines are expected to conform
+to RFC 4516 format.  The
+.BR ldap_url (3)
+routines can be used to work with LDAP URLs.
+.LP
+LDAP controls to be passed to routines can be manipulated using the
+.BR ldap_controls (3)
+routines.
 .SH DISPLAYING RESULTS
-Results obtained from the ldap search routines can be output by hand,
+Results obtained from the search routines can be output by hand,
 by calling
 .BR ldap_first_entry (3)
 and
@@ -74,32 +111,15 @@ to step through an entry's attributes, and
 .BR ldap_get_values (3)
 to retrieve a given attribute's values.  Attribute values
 may or may not be displayable.
-.SH CONTROLS
-This library supports both LDAP Version 2 and Version 3, with the Version 2
-protocol selected by default.
-LDAP Version 3 operations can be extended through the use of controls. Controls
-can be sent to a server or returned to the client with any LDAP message.
-Extended versions of the standard routines are available for use with
-controls. These routines are generally named by adding
-.BR _ext
-to the regular routine's name.
-.SH UNIFORM RESOURCE LOCATORS (URLS)
-The
-.BR ldap_url (3)
-routines can be used to test a URL to see if it is an LDAP URL, to parse LDAP
-URLs into their component pieces, and to initiate searches directly using
-an LDAP URL.
-.SH CACHING
-The
-.BR ldap_cache (3)
-routines implement a local client caching scheme,
-providing a substantial performance increase for repeated queries.
-Caching is experiemental.
 .SH UTILITY ROUTINES
 Also provided are various utility routines.  The
 .BR ldap_sort (3)
 routines are used to sort the entries and values returned via
 the ldap search routines. 
+.SH DEPRECATED INTERFACES
+A number of interfaces are now considered deprecated.  For instance,
+ldap_add(3) is deprecated in favor of ldap_add_ext(3).
+.so Deprecated
 .SH BER LIBRARY
 Also included in the distribution is a set of lightweight Basic
 Encoding Rules routines.  These routines are used by the LDAP library
@@ -116,98 +136,64 @@ and
 .BR lber\-types (3).
 .SH INDEX
 .TP 20
-.SM ldap_open(3)
-open a connection to an LDAP server (deprecated, use
-.BR ldap_init (3))
-.TP
-.SM ldap_init(3)
-initialize the LDAP library without opening a connection to a server
-.TP
 .SM ldap_initialize(3)
 initialize the LDAP library without opening a connection to a server
 .TP
 .SM ldap_result(3)
 wait for the result from an asynchronous operation
 .TP
-.SM ldap_abandon(3)
+.SM ldap_abandon_ext(3)
 abandon (abort) an asynchronous operation
 .TP
-.SM ldap_add(3)
+.SM ldap_add_ext(3)
 asynchronously add an entry
 .TP
-.SM ldap_add_s(3)
+.SM ldap_add_ext_s(3)
 synchronously add an entry
 .TP
-.SM ldap_bind(3)
+.SM ldap_sasl_bind(3)
 asynchronously bind to the directory
 .TP
-.SM ldap_bind_s(3)
+.SM ldap_sasl_bind_s(3)
 synchronously bind to the directory
 .TP
-.SM ldap_simple_bind(3)
-asynchronously bind to the directory using simple authentication
-.TP
-.SM ldap_simple_bind_s(3)
-synchronously bind to the directory using simple authentication
-.TP
-.SM ldap_unbind(3)
+.SM ldap_unbind_ext(3)
 synchronously unbind from the LDAP server and close the connection
 .TP
-.SM ldap_unbind_s(3)
+.SM ldap_unbind(3) and ldap_unbind_s(3) are
 equivalent to
-.BR ldap_unbind (3)
+.BR ldap_unbind_ext (3)
 .TP
-.SM ldap_memfree (3)
+.SM ldap_memfree(3)
 dispose of memory allocated by LDAP routines.
 .TP
-.SM ldap_enable_cache(3)
-enable LDAP client caching
-.TP
-.SM ldap_disable_cache(3)
-disable LDAP client caching
-.TP
-.SM ldap_destroy_cache(3)
-disable LDAP client caching and destroy cache contents
-.TP
-.SM ldap_flush_cache(3)
-flush LDAP client cache
-.TP
-.SM ldap_uncache_entry(3)
-uncache requests pertaining to an entry
-.TP
-.SM ldap_uncache_request(3)
-uncache a request
-.TP
-.SM ldap_set_cache_options(3)
-set cache options
-.TP
-.SM ldap_compare(3)
+.SM ldap_compare_ext(3)
 asynchronously compare to a directory entry
 .TP
-.SM ldap_compare_s(3)
+.SM ldap_compare_ext_s(3)
 synchronously compare to a directory entry
 .TP
-.SM ldap_delete(3)
+.SM ldap_delete_ext(3)
 asynchronously delete an entry
 .TP
-.SM ldap_delete_s(3)
+.SM ldap_delete_ext_s(3)
 synchronously delete an entry
 .TP
-.SM ldap_perror(3)
-print an LDAP error indication to standard error
-.TP
 .SM ld_errno(3)
 LDAP error indication
 .TP
-.SM ldap_result2error(3)
-extract LDAP error indication from LDAP result
-.TP
 .SM ldap_errlist(3)
 list of LDAP errors and their meanings
 .TP
 .SM ldap_err2string(3)
 convert LDAP error indication to a string
 .TP
+.SM ldap_extended_operation(3)
+asynchronously perform an arbitrary extended operation
+.TP
+.SM ldap_extended_operation_s(3)
+synchronously perform an arbitrary extended operation
+.TP
 .SM ldap_first_attribute(3)
 return first attribute name in an entry
 .TP
@@ -226,50 +212,29 @@ return number of entries in a search result
 .SM ldap_get_dn(3)
 extract the DN from an entry
 .TP
-.SM ldap_explode_dn(3)
-convert a DN into its component parts
-.TP
-.SM ldap_explode_rdn(3)
-convert an RDN into its component parts
-.TP
-.SM ldap_get_values(3)
-return an attribute's values
-.TP
 .SM ldap_get_values_len(3)
 return an attribute's values with lengths
 .TP
-.SM ldap_value_free(3)
-free memory allocated by ldap_get_values(3)
-.TP
 .SM ldap_value_free_len(3)
 free memory allocated by ldap_get_values_len(3)
 .TP
-.SM ldap_count_values(3)
-return number of values
-.TP
 .SM ldap_count_values_len(3)
 return number of values
 .TP
-.SM ldap_modify(3)
+.SM ldap_modify_ext(3)
 asynchronously modify an entry
 .TP
-.SM ldap_modify_s(3)
+.SM ldap_modify_ext_s(3)
 synchronously modify an entry
 .TP
 .SM ldap_mods_free(3)
-free array of pointers to mod structures used by ldap_modify(3)
+free array of pointers to mod structures used by ldap_modify_ext(3)
 .TP
-.SM ldap_modrdn2(3)
-asynchronously modify the RDN of an entry
+.SM ldap_rename(3)
+asynchronously rename an entry
 .TP
-.SM ldap_modrdn2_s(3)
-synchronously modify the RDN of an entry
-.TP
-.SM ldap_modrdn(3)
-deprecated - use ldap_modrdn2(3)
-.TP
-.SM ldap_modrdn_s(3)
-depreciated - use ldap_modrdn2_s(3)
+.SM ldap_rename_s(3)
+synchronously rename an entry
 .TP
 .SM ldap_msgfree(3)
 free results allocated by ldap_result(3)
@@ -280,15 +245,12 @@ return the message type of a message from ldap_result(3)
 .SM ldap_msgid(3)
 return the message id of a message from ldap_result(3)
 .TP
-.SM ldap_search(3)
+.SM ldap_search_ext(3)
 asynchronously search the directory
 .TP
-.SM ldap_search_s(3)
+.SM ldap_search_ext_s(3)
 synchronously search the directory
 .TP
-.SM ldap_search_st(3)
-synchronously search the directory with timeout
-.TP
 .SM ldap_is_ldap_url(3)
 check a URL string to see if it is an LDAP URL
 .TP
@@ -304,14 +266,13 @@ sort a list of attribute values
 .SM ldap_sort_strcasecmp(3)
 case insensitive string comparison
 .SH SEE ALSO
-.BR slapd (8)
+.BR ldap.conf (5),
+.BR slapd (8),
 .BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org>
 .SH ACKNOWLEDGEMENTS
-.B	OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B	OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.  
+.so ../Project
 .LP
-These API manual pages are based upon descriptions provided in the
-IETF C LDAP API Internet Draft, a work in progress, edited by
-Mark Smith.
+These API manual pages are loosely based upon descriptions provided
+in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work
+in progress.
+