X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Fldap_result.3;h=607eed15fb12021571f0c6b33043ac21c0359c9a;hb=2be146e20ffdabe32514445b6034e40cb7df77be;hp=cf8cadb5bf1f81ae3061544ee26701da27757aa8;hpb=3a119bf1f7e264592868067f8e2d93ca26b14026;p=openldap

diff --git a/doc/man/man3/ldap_result.3 b/doc/man/man3/ldap_result.3
index cf8cadb5bf..607eed15fb 100644
--- a/doc/man/man3/ldap_result.3
+++ b/doc/man/man3/ldap_result.3
@@ -1,34 +1,26 @@
-.TH LDAP_RESULT 3 "22 September 1998" "OpenLDAP LDVERSION"
+.TH LDAP_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
 ldap_result \- Wait for the result of an LDAP operation
+.SH LIBRARY
+OpenLDAP LDAP (libldap, -lldap)
 .SH SYNOPSIS
 .nf
 .ft B
-#include <lber.h>
 #include <ldap.h>
 .LP
 .ft B
-int ldap_result(ld, msgid, all, timeout, result)
+int ldap_result( LDAP *ld, int msgid, int all,
+	struct timeval *timeout, LDAPMessage **result );
+
+int ldap_msgfree( LDAPMessage *msg );
+
+int ldap_msgtype( LDAPMessage *msg );
+
+int ldap_msgid( LDAPMessage *msg );
 .ft
-LDAP *ld;
-int msgid, all;
-struct timeval *timeout;
-LDAPMessage **result;
-.LP
-.ft B
-int ldap_msgfree(msg)
-.ft
-LDAPMessage *msg;
-.LP
-.ft B
-int ldap_msgtype(msg)
-.ft
-LDAPMessage *msg;
-.LP
-.ft B
-int ldap_msgid(msg)
-.ft
-LDAPMessage *msg;
 .SH DESCRIPTION
 The
 .B ldap_result()
@@ -59,49 +51,60 @@ for further details.
 .LP
 If the result of a specific operation is required, \fImsgid\fP should
 be set to the invocation identifier returned when the operation was
-initiated, otherwise LDAP_RES_ANY should be supplied.  The \fIall\fP
-parameter only has meaning for search responses and is used to select
-whether a single entry of the search response should be returned, or
-all results of the search should be returned.
+initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be
+supplied to wait for any or unsolicited response.
+.LP
+The \fIall\fP parameter, if non-zero, causes
+.B ldap_result()
+to return all responses with msgid, otherwise only the
+next response is returned.  This is commonly used to obtain all
+the responses of a search operation.
 .LP
 A search response is made up of zero or
-more search entries followed by a search result.  If \fIall\fP is set
-to 0, search entries will be returned one at a time as they come in,
-via separate calls to
+more search entries, zero or more search references, and zero or
+more extended partial responses followed by a search result.  If
+\fIall\fP is set to 0, search entries will be returned one at a
+time as they come in, via separate calls to
 .BR ldap_result() .
 If it's set to 1, the search
-response will only be returned in its entirety, i.e., after all entries
-and the final search result have been received.
+response will only be returned in its entirety, i.e., after all entries,
+all references, all extended partial responses, and the final search
+result have been received.
 .LP
 Upon success, the type of the result received is returned and the
-\fIresult\fP parameter will contain the result of the operation.  This
+\fIresult\fP parameter will contain the result of the operation;
+otherwise, the \fIresult\fP parameter is undefined.  This
 result should be passed to the LDAP parsing routines,
-.BR ldap_first_entry (3)
+.BR ldap_first_message (3)
 and friends, for interpretation.
 .LP
 The possible result types returned are:
 .LP
 .nf
-	#define LDAP_RES_BIND			0x61L
-	#define LDAP_RES_SEARCH_ENTRY		0x64L
-	#define LDAP_RES_SEARCH_RESULT		0x65L
-	#define LDAP_RES_MODIFY			0x67L
-	#define LDAP_RES_ADD			0x69L
-	#define LDAP_RES_DELETE			0x6bL
-	#define LDAP_RES_MODRDN			0x6dL
-	#define LDAP_RES_COMPARE		0x6fL
+	LDAP_RES_BIND (0x61)
+	LDAP_RES_SEARCH_ENTRY (0x64)
+	LDAP_RES_SEARCH_REFERENCE (0x73)
+	LDAP_RES_SEARCH_RESULT (0x65)
+	LDAP_RES_MODIFY (0x67)
+	LDAP_RES_ADD (0x69)
+	LDAP_RES_DELETE (0x6b)
+	LDAP_RES_MODDN (0x6d)
+	LDAP_RES_COMPARE (0x6f)
+	LDAP_RES_EXTENDED (0x78)
+	LDAP_RES_EXTENDED_PARTIAL (0x79)
 .fi
 .LP
 The
 .B ldap_msgfree()
 routine is used to free the memory allocated for
-a result by
+result(s) by
 .B ldap_result()
 or
 .BR ldap_search_s (3)
-and friends.  It takes
-a pointer to the result to be freed and returns the type of the
-message it freed.
+and friends.
+It takes a pointer to the result or result chain to be freed and returns
+the type of the last message in the chain.
+If the parameter is NULL, the function does nothing and returns zero.
 .LP
 The
 .B ldap_msgtype()
@@ -118,16 +121,13 @@ timeout specified was exceeded.
 and
 .B ldap_msgid()
 return -1 on error.
-.SH NOTES
-This routine dynamically allocates memory for results that it receives.
-The memory can be freed by the caller using
-.BR ldap_msgfree .
 .SH SEE ALSO
 .BR ldap (3),
 .BR ldap_search (3),
+.BR ldap_first_message (3),
 .BR select (2)
 .SH ACKNOWLEDGEMENTS
-.B	OpenLDAP
+.B OpenLDAP
 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B	OpenLDAP
+.B OpenLDAP
 is derived from University of Michigan LDAP 3.3 Release.