From 7f4ff18bd44f73210f11cd7da4c88b665374f97d Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Thu, 18 Dec 2003 02:12:44 +0000 Subject: [PATCH] Update index to encourage "proper" use --- doc/man/man3/ldap.3 | 170 +++++++++++++++++++------------------------- 1 file changed, 73 insertions(+), 97 deletions(-) diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 index 24b364f1f3..32b7a28730 100644 --- a/doc/man/man3/ldap.3 +++ b/doc/man/man3/ldap.3 @@ -14,13 +14,14 @@ OpenLDAP LDAP (libldap, -lldap) .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 3377) 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 (RFC2251), LDAP over TLS/SSL, and LDAP over IPC (UNIX +domain sockets). This API supports SASL (RFC2829) and Start TLS +(RFC2830) 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), @@ -34,17 +35,16 @@ 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. +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. Subsequently, other operations are performed by calling one of the synchronous or asynchronous routines (e.g., .BR ldap_search_ext_s (3) or @@ -58,11 +58,38 @@ 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 +.SH LDAP versions +This library supports version 3 of the Lightweight Directory Access +Protocol (LDAPv3) as defined in RFC 3377. It also supports a varient +of version 2 of LDAP as defined by U-Mich LDAP and, to some degree, +RFC 1777. Version 2 (all varients) should be viewed as 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 2253. The +.BR ldap_explode_dn (3) +routines can be used to work with DNs. +.LP +Search filters to be passed to the search routines are to be constructed by hand and should conform to RFC 2254. +.LP +LDAP URL are to be passed to routines are expected to conform +to RFC 2255. +The +.BR ldap_url (3) +routines can be used to work with LDAP URLs. .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 @@ -76,21 +103,6 @@ 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 UTILITY ROUTINES Also provided are various utility routines. The .BR ldap_sort (3) @@ -112,71 +124,52 @@ 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_ext_s(3) equivalent to -.BR ldap_unbind (3) +.BR ldap_unbind_ext (3) .TP .SM ldap_memfree(3) dispose of memory allocated by LDAP routines. .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 @@ -202,49 +195,34 @@ return number of entries in a search result extract the DN from an entry .TP .SM ldap_explode_dn(3) -convert a DN into its component parts +convert a DN into its component parts (deprecated) .TP .SM ldap_explode_rdn(3) -convert an RDN into its component parts -.TP -.SM ldap_get_values(3) -return an attribute's values +convert an RDN into its component parts (deprecated) .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) -.TP -.SM ldap_modrdn2(3) -asynchronously modify the RDN of an entry +free array of pointers to mod structures used by ldap_modify_ext(3) .TP -.SM ldap_modrdn2_s(3) -synchronously modify the RDN of an entry +.SM ldap_rename(3) +asynchronously rename 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) @@ -255,15 +233,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 @@ -288,6 +263,7 @@ is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). .B OpenLDAP is derived from University of Michigan LDAP 3.3 Release. .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. + -- 2.39.5