--- doc/man/man3/ldap.3 2005/07/10 04:36:40 1.34.2.2 +++ doc/man/man3/ldap.3 2011/01/04 23:49:43 1.40.2.8 @@ -1,11 +1,11 @@ .TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION" -.\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap.3,v 1.36 2005/07/04 04:57:10 hallvard Exp $ -.\" Copyright 1998-2005 The OpenLDAP Foundation All Rights Reserved. +.\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap.3,v 1.40.2.7 2010/04/13 20:22:37 kurt Exp $ +.\" 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) +OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B @@ -14,12 +14,12 @@ OpenLDAP LDAP (libldap, -lldap) .fi .SH DESCRIPTION .LP -The Lightweight Directory Access Protocol (LDAP) (RFC 3377) provides +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 (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 +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 @@ -39,16 +39,21 @@ created using 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. +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. Subsequently, 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 @@ -60,9 +65,9 @@ Errors can be interpreted by calling .BR ldap_err2string (3). .SH LDAP versions This library supports version 3 of the Lightweight Directory Access -Protocol (LDAPv3) as defined in RFC 3377. It also supports a variant +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) should be viewed as obsolete. +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. @@ -72,22 +77,25 @@ should use 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 +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. +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 2254. +constructed by hand and should conform to RFC 4515 UTF-8 +string representation. .LP -LDAP URL are to be passed to routines are expected to conform -to RFC 2255. -The +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 search routines can be output by hand, by calling @@ -108,6 +116,10 @@ Also provided are various utility routin .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 @@ -148,7 +160,7 @@ synchronously bind to the directory .SM ldap_unbind_ext(3) synchronously unbind from the LDAP server and close the connection .TP -.SM ldap_unbind_ext_s(3) +.SM ldap_unbind(3) and ldap_unbind_s(3) are equivalent to .BR ldap_unbind_ext (3) .TP @@ -176,6 +188,12 @@ list of LDAP errors and their meanings .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 @@ -194,12 +212,6 @@ return number of entries in a search res .SM ldap_get_dn(3) extract the DN from an entry .TP -.SM ldap_explode_dn(3) -convert a DN into its component parts (deprecated) -.TP -.SM ldap_explode_rdn(3) -convert an RDN into its component parts (deprecated) -.TP .SM ldap_get_values_len(3) return an attribute's values with lengths .TP @@ -258,10 +270,7 @@ case insensitive string comparison .BR slapd (8), .BR draft-ietf-ldapext-ldap-c-api-xx.txt \ .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 loosely based upon descriptions provided in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work