From 0480296a1f41cd46b999499b02afa5cc26a2ec1e Mon Sep 17 00:00:00 2001
From: Pierangelo Masarati <ando@openldap.org>
Date: Tue, 27 Jul 2010 00:47:18 +0000
Subject: [PATCH] document ldap_set_urllist_proc(3) (ITS#6601)

---
 doc/man/man3/ldap_open.3       | 34 ++++++++++++++++++++++++++++++++++
 doc/man/man3/ldap_open.3.links |  2 ++
 2 files changed, 36 insertions(+)

diff --git a/doc/man/man3/ldap_open.3 b/doc/man/man3/ldap_open.3
index 54c30c9cae..f01487470d 100644
--- a/doc/man/man3/ldap_open.3
+++ b/doc/man/man3/ldap_open.3
@@ -30,6 +30,21 @@ LDAP **ldp;
 char *uri;
 .LP
 .ft B
+int ldap_set_urllist_proc(ld, proc, params)
+.ft
+LDAP *ld;
+LDAP_URLLIST_PROC *proc;
+void *params;
+.LP
+.ft B
+int (LDAP_URLLIST_PROC)(ld, urllist, url, params);
+.ft
+LDAP *ld;
+LDAPURLDesc **urllist;
+LDAPURLDesc **url;
+void *params;
+.LP
+.ft B
 #include <ldap_pvt.h>
 .LP
 .ft B
@@ -140,6 +155,23 @@ was built with LDAP_CONNECTIONLESS defined.
 The
 .I uri
 parameter may optionally be provided for informational purposes.
+.LP
+.B ldap_set_urllist_proc()
+allows to set a function
+.I proc
+of type
+.I LDAP_URLLIST_PROC
+that is called when a successful connection can be established.
+This function receives the list of URIs parsed from the
+.I uri
+string originally passed to
+.BR ldap_initialize() ,
+and the one that successfully connected.
+The function may manipulate the URI list; the typical use consists
+in moving the successful URI to the head of the list,
+so that subsequent attempts to connect to one of the URIs using the same LDAP handle
+will try it first.
+By default, this function is not defined.
 
 Note: the first call into the LDAP library also initializes the global
 options for the library. As such the first call should be single-threaded
@@ -168,6 +200,8 @@ will directly return the LDAP code associated to the error (or
 in case of success);
 .I errno
 should be set as well whenever appropriate.
+.B ldap_set_urllist_proc()
+returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success.
 .SH SEE ALSO
 .BR ldap (3),
 .BR ldap_bind (3),
diff --git a/doc/man/man3/ldap_open.3.links b/doc/man/man3/ldap_open.3.links
index d2f912c0b2..aa34ab7617 100644
--- a/doc/man/man3/ldap_open.3.links
+++ b/doc/man/man3/ldap_open.3.links
@@ -1,2 +1,4 @@
 ldap_init.3
 ldap_initialize.3
+ldap_set_urllist_proc.3
+ldap_init_fd.3
-- 
2.39.5