1.lf 1 stdin
2.TH LDAP_OPEN 3 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
5.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
6.SH NAME
7ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles
8.SH LIBRARY
9OpenLDAP LDAP (libldap, \-lldap)
10.SH SYNOPSIS
11.nf
12.ft B
13#include <ldap.h>
14.LP
15.ft B
16LDAP *ldap_dup(
17.RS
18.ft B
19LDAP *\fIold\fB );
20.RE
21.LP
22.ft B
23int ldap_destroy(
24.RS
25.ft B
26LDAP *\fIold\fB );
27.RE
28.SH DESCRIPTION
29.LP
30.B ldap_dup()
31duplicates an existing LDAP
32.RB ( "LDAP *" )
33session handle.
34The new session handle may be used concurrently with the
35original session handle.
36In a threaded environment, different threads may execute concurrent
37requests on the same connection/session without fear of contamination.
38Each session handle manages its own private error results.
39.LP
40.B ldap_destroy()
41destroys an existing session handle.
42.LP
43The
44.B ldap_dup()
45and
46.B ldap_destroy()
47functions are used in conjunction with a "thread safe" version
48of
49.B libldap
50.RB ( libldap_r )
51to enable operation thread safe API calls, so that a single session
52may be simultaneously used across multiple threads with consistent
53error handling.
54.LP
55When a session is created through the use of one of the session creation
56functions including
57.BR ldap_open (3),
58.BR ldap_init (3),
59.BR ldap_initialize (3)
60or
61.BR ldap_init_fd (3)
62an
63.B "LDAP *"
64session handle is returned to the application.
65The session handle may be shared amongst threads, however the
66error codes are unique to a session handle.
67Multiple threads performing different operations using the same
68session handle will result in inconsistent error codes and
69return values.
70.LP
71To prevent this confusion,
72.B ldap_dup()
73is used duplicate an existing session handle so that multiple threads
74can share the session, and maintain consistent error information
75and results.
76.LP
77The message queues for a session are shared between sibling session handles.
78Results of operations on a sibling session handles are accessible
79to all the sibling session handles.
80Applications desiring results associated with a specific operation
81should provide the appropriate msgid to
82.BR ldap_result() .
83Applications should avoid calling
84.B ldap_result()
85with
86.B LDAP_RES_ANY
87as that may "steal" and return results in the calling thread
88that another operation in a different thread, using a
89different session handle, may require to complete.
90.LP
91When
92.B ldap_unbind()
93is called on a session handle with siblings, all the 
94siblings become invalid.
95.LP
96Siblings must be destroyed using
97.BR ldap_destroy() .
98Session handle resources associated with the original
99.RB ( "LDAP *" )
100will be freed when the last session handle is destroyed or when
101.B ldap_unbind()
102is called, if no other session handles currently exist.
103.SH ERRORS
104If an error occurs,
105.B ldap_dup()
106will return NULL and 
107.I errno
108should be set appropriately.
109.B ldap_destroy()
110will directly return the LDAP code associated to the error (or
111.I LDAP_SUCCESS
112in case of success);
113.I errno
114should be set as well whenever appropriate.
115.SH SEE ALSO
116.BR ldap_open (3),
117.BR ldap_init (3),
118.BR ldap_initialize (3),
119.BR ldap_init_fd (3),
120.BR errno (3)
121.SH ACKNOWLEDGEMENTS
122This work is based on the previously proposed
123.B LDAP C API Concurrency Extensions
124draft
125.BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt )
126effort.
127.lf 1 ./../Project
128.\" Shared Project Acknowledgement Text
129.B "OpenLDAP Software"
130is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
131.B "OpenLDAP Software"
132is derived from the University of Michigan LDAP 3.3 Release.  
133.lf 127 stdin
134