document ldap_set_urllist_proc(3) (ITS#6601)

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),

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