From 0e847131e03621551d27478112fc08130b35146d Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Sun, 13 Jan 2002 12:55:55 +0000 Subject: [PATCH] Minor updates, mention extended requests, server and client controls. Please review and comment. --- doc/man/man3/ldap.3 | 40 ++++++++++++++++++-------- doc/man/man3/ldap_abandon.3 | 38 ++++++++++++++++++------- doc/man/man3/ldap_add.3 | 57 +++++++++++++++++++++++++------------ 3 files changed, 94 insertions(+), 41 deletions(-) diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 index ed926cd698..db59773fc4 100644 --- a/doc/man/man3/ldap.3 +++ b/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) diff --git a/doc/man/man3/ldap_abandon.3 b/doc/man/man3/ldap_abandon.3 index dc70df2b92..63e75446cd 100644 --- a/doc/man/man3/ldap_abandon.3 +++ b/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 -.LP -.ft B -int ldap_abandon(ld, msgid) -.ft -LDAP *ld; -int msgid; +.B #include +.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 diff --git a/doc/man/man3/ldap_add.3 b/doc/man/man3/ldap_add.3 index a1d996cd09..7a3aad11d3 100644 --- a/doc/man/man3/ldap_add.3 +++ b/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 -.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 +.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) -- 2.39.5