Minor updates, mention extended requests, server and client controls.

Please review and comment.

doc/man/man3/ldap.3

@@ -1,4 +1,4 @@
-.TH LDAP 3 "1 August 2001" "OpenLDAP LDVERSION"
+.TH LDAP 3 "13 January 2002" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
@@ -30,9 +30,14 @@ Both synchronous and asynchronous APIs are provided.  Also included are
 various routines to parse the results returned from these routines.
 These routines are found in the \-lldap library.
 .LP
-The basic interaction is as follows.  A session handle associated
-with created using
-.BR ldap_init (3).
+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
@@ -67,12 +72,19 @@ and
 .BR ldap_next_attribute (3)
 to step through an entry's attributes, and
 .BR ldap_get_values (3)
-to retrieve a given attribute's value.  Attribute values
+to retrieve a given attribute's values.  Attribute values
 may or may not be displayable.
+.SH CONTROLS
+LDAP 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 test a URL to see if it is an LDAP URL, to parse LDAP
+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
@@ -103,11 +115,15 @@ and
 .SH INDEX
 .TP 20
 .SM ldap_open(3)
-open a connection to an LDAP server
+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
@@ -164,10 +180,10 @@ uncache a request
 set cache options
 .TP
 .SM ldap_compare(3)
-asynchronous compare to a directory entry
+asynchronously compare to a directory entry
 .TP
 .SM ldap_compare_s(3)
-synchronous compare to a directory entry
+synchronously compare to a directory entry
 .TP
 .SM ldap_delete(3)
 asynchronously delete an entry
@@ -185,7 +201,7 @@ LDAP error indication
 extract LDAP error indication from LDAP result
 .TP
 .SM ldap_errlist(3)
-list of ldap errors and their meanings
+list of LDAP errors and their meanings
 .TP
 .SM ldap_err2string(3)
 convert LDAP error indication to a string
@@ -212,13 +228,13 @@ extract the DN from an entry
 convert a DN into its component parts
 .TP
 .SM ldap_explode_rdn(3)
-convert a RDN into its component parts
+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 values with lengths
+return an attribute's values with lengths
 .TP
 .SM ldap_value_free(3)
 free memory allocated by ldap_get_values(3)

doc/man/man3/ldap_abandon.3

@@ -1,19 +1,19 @@
-.TH LDAP_ABANDON 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_ABANDON 3 "13 January 2002" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ldap_abandon \- Abandon an LDAP operation in progress
+ldap_abandon, ldap_abandon_ext \- Abandon an LDAP operation in progress
 .SH SYNOPSIS
 .nf
-.ft B
-#include <ldap.h>
-.LP
-.ft B
-int ldap_abandon(ld, msgid)
-.ft
-LDAP *ld;
-int msgid;
+.B #include <ldap.h>
+.sp
+.BI "int ldap_abandon(LDAP *" ld ", int " msgid ");"
+.sp
+.BI "int ldap_abandon_ext(LDAP *" ld ", int " msgid ","
+.RS
+.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);"
+.fi
 .SH DESCRIPTION
 The
 .B ldap_abandon()
@@ -32,10 +32,26 @@ it sends an LDAP abandon operation to the the LDAP server.
 The caller can expect that the result of an abandoned operation
 will not be returned from a future call to
 .BR ldap_result (3).
+.LP
+.B ldap_abandon_ext()
+is equivalent to
+.B ldap_abandon()
+except that it allows server and client controls to be passed
+in
+.I sctrls
+and
+.IR cctrls ,
+respectively.
 .SH ERRORS
 .B ldap_abandon()
 returns 0 if everything goes ok, -1 otherwise,
-setting \fIld_errno\fP appropriately. See
+setting \fIld_errno\fP with an appropriate LDAP error code.
+.LP
+.B ldap_abandon_ext()
+directly returns an LDAP error code indicating success or failure of the
+operation.
+.LP
+See
 .BR ldap_error (3)
 for details.
 .SH SEE ALSO

doc/man/man3/ldap_add.3

@@ -1,27 +1,27 @@
-.TH LDAP_ADD 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_ADD 3 "13 January 2002" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ldap_add, ldap_add_s \- Perform an LDAP add operation
+ldap_add, ldap_add_s, ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation
 .SH SYNOPSIS
 .nf
-.ft B
-#include <ldap.h>
-.LP
-.ft B
-int ldap_add(ld, dn, attrs)
-.ft
-LDAP *ld;
-char *dn;
-LDAPMod *attrs[];
-.LP
-.ft B
-int ldap_add_s(ld, dn, attrs)
-.ft
-LDAP *ld;
-char *dn;
-LDAPMod *attrs[];
+.B #include <ldap.h>
+.sp
+.BI "int ldap_add(LDAP *" ld ", const char *" dn ", LDAPMOD *" attrs "[]);"
+.sp
+.BI "int ldap_add_s(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[]);"
+.sp
+.BI "int ldap_add_ext(LDAP *" ld ", const char *" dn ", LDAPMOD *" attrs "[],"
+.RS
+.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[], int *" msgidp ");"
+.RE
+.sp
+.BI "int ldap_add_ext_s(LDAP *" ld ", const char *" dn ", LDAPMOD *" attrs "[],"
+.RS
+.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);"
+.RE
+.fi
 .SH DESCRIPTION
 The
 .B ldap_add_s()
@@ -49,6 +49,23 @@ routine works just like
 but it is asynchronous.  It returns the message id of the request it
 initiated.  The result of this operation can be obtained by calling
 .BR ldap_result (3).
+.LP
+The
+.B ldap_add_ext()
+routine allows server and client controls to be specified to extend
+the add request. This routine is asynchronous like
+.BR ldap_add() ,
+but its return value is an LDAP error code.  It stores the message id
+of the request in the integer pointed to
+by
+.IR msgidp .
+.LP
+The
+.B ldap_add_ext_s()
+routine is the synchronous version of
+.BR ldap_add_ext() .
+It also returns an LDAP error code indicating success or failure
+of the operation.
 .SH ERRORS
 .B ldap_add()
 returns -1 in case of error initiating the request, and
@@ -57,6 +74,10 @@ to indicate the error.
 .B ldap_add_s()
 will return an LDAP error code
 directly (LDAP_SUCCESS if everything went ok, some error otherwise).
+.B ldap_add_ext()
+and
+.B ldap_add_ext_s()
+also directly return LDAP error codes.
 .SH SEE ALSO
 .BR ldap(3),
 .B ldap_modify(3)