From 282a3c537a9ab2f805a2f428606a3da3fa1705d5 Mon Sep 17 00:00:00 2001
From: Howard Chu <hyc@openldap.org>
Date: Mon, 12 Feb 2007 04:43:03 +0000
Subject: [PATCH] ITS#4707 added ldap_init_fd()

---
 doc/man/man3/ldap_open.3 | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/doc/man/man3/ldap_open.3 b/doc/man/man3/ldap_open.3
index 604b11c117..46b67e11f3 100644
--- a/doc/man/man3/ldap_open.3
+++ b/doc/man/man3/ldap_open.3
@@ -28,6 +28,17 @@ int ldap_initialize(ldp, uri)
 .ft
 LDAP **ldp;
 char *uri;
+.LP
+.ft B
+#include <ldap_pvt.h>
+.LP
+.ft B
+int ldap_init_fd(fd, proto, uri, ldp)
+.ft
+ber_socket_t fd;
+int proto;
+char *uri;
+LDAP **ldp;
 .SH DESCRIPTION
 .LP
 .B ldap_open()
@@ -37,8 +48,12 @@ the connection and to maintain per-connection information.
 .B ldap_init()
 allocates an LDAP structure but does not open an initial connection.
 .B ldap_initialize()
-allocates an LDAP structure but does not open an initial connection.  One
-of these three routines must be called before any operations are attempted.
+allocates an LDAP structure but does not open an initial connection.
+.B ldap_init_fd()
+allocates an LDAP structure using an existing connection on the
+provided socket.
+One
+of these routines must be called before any operations are attempted.
 .LP
 .B ldap_open()
 takes \fIhost\fP, the hostname on which the LDAP server is
@@ -87,6 +102,23 @@ are deprecated in favor of
 .BR ldap_initialize() ,
 essentially because the latter allows to specify a schema in the URI
 and it explicitly returns an error code.
+.LP
+.B ldap_init_fd()
+allows an LDAP structure to be initialized using an already-opened
+connection. The
+.I proto
+parameter should be one of
+.BR LDAP_PROTO_TCP ,
+.BR LDAP_PROTO_UDP ,
+or 
+.B LDAP_PROTO_IPC
+for a connection using TCP, UDP, or IPC, respectively. The value
+.B LDAP_PROTO_EXT
+may also be specified if user-supplied sockbuf handlers are going to
+be used. The
+.I uri
+parameter may optionally be provided for informational purposes.
+
 .SH ERRORS
 If an error occurs,
 .B ldap_open()
@@ -94,6 +126,8 @@ and
 .B ldap_init()
 will return NULL and errno should be set appropriately.
 .B ldap_initialize()
+and
+.B ldap_init_fd()
 will directly return the LDAP code associated to the error (or
 .I LDAP_SUCCESS
 in case of success);
@@ -103,6 +137,7 @@ errno should be set as well whenever appropriate.
 .BR ldap_bind (3),
 .BR ldap_get_option (3),
 .BR ldap_set_option (3),
+.BR lber-sockbuf (3),
 .BR errno (3)
 .SH ACKNOWLEDGEMENTS
 .so ../Project
-- 
2.39.5