1LDAP_OPEN(3)               Library Functions Manual               LDAP_OPEN(3)
2
3
4

NAME

6       ldap_dup, ldap_destroy, - Duplicate and destroy LDAP session handles
7

LIBRARY

9       OpenLDAP LDAP (libldap, -lldap)
10

SYNOPSIS

12       #include <ldap.h>
13
14       LDAP *ldap_dup(
15              LDAP *old );
16
17       int ldap_destroy(
18              LDAP *old );
19

DESCRIPTION

21       ldap_dup()  duplicates  an  existing LDAP (LDAP *) session handle.  The
22       new session handle may be used concurrently with the  original  session
23       handle.   In a threaded environment, different threads may execute con‐
24       current requests on the same connection/session without fear of contam‐
25       ination.  Each session handle manages its own private error results.
26
27       ldap_destroy() destroys an existing session handle.
28
29       The  ldap_dup()  and  ldap_destroy()  functions are used in conjunction
30       with a "thread safe" version of libldap to enable operation thread safe
31       API  calls,  so that a single session may be simultaneously used across
32       multiple threads with consistent error handling.
33
34       When a session is created through the use of one of  the  session  cre‐
35       ation  functions  including  ldap_open(3),  ldap_init(3), ldap_initial‐
36       ize(3) or ldap_init_fd(3) an LDAP * session handle is returned  to  the
37       application.  The session handle may be shared amongst threads, however
38       the error codes are unique to a session handle.  Multiple threads  per‐
39       forming  different operations using the same session handle will result
40       in inconsistent error codes and return values.
41
42       To prevent this confusion, ldap_dup() is  used  duplicate  an  existing
43       session  handle  so  that  multiple  threads can share the session, and
44       maintain consistent error information and results.
45
46       The message queues for a session are  shared  between  sibling  session
47       handles.  Results of operations on a sibling session handles are acces‐
48       sible to all the sibling session handles.   Applications  desiring  re‐
49       sults associated with a specific operation should provide the appropri‐
50       ate msgid to ldap_result().  Applications should avoid calling ldap_re‐
51       sult()  with LDAP_RES_ANY as that may "steal" and return results in the
52       calling thread that another operation in a different  thread,  using  a
53       different session handle, may require to complete.
54
55       When ldap_unbind() is called on a session handle with siblings, all the
56       siblings become invalid.
57
58       Siblings must be destroyed using ldap_destroy().   Session  handle  re‐
59       sources  associated  with  the original (LDAP *) will be freed when the
60       last session handle is destroyed or when ldap_unbind() is called, if no
61       other session handles currently exist.
62

ERRORS

64       If an error occurs, ldap_dup() will return NULL and errno should be set
65       appropriately.  ldap_destroy() will directly return the LDAP code asso‐
66       ciated  to the error (or LDAP_SUCCESS in case of success); errno should
67       be set as well whenever appropriate.
68

SEE ALSO

70       ldap_open(3), ldap_init(3),  ldap_initialize(3),  ldap_init_fd(3),  er‐
71       rno(3)
72

ACKNOWLEDGEMENTS

74       This  work  is  based on the previously proposed LDAP C API Concurrency
75       Extensions draft (draft-zeilenga-ldap-c-api-concurrency-00.txt) effort.
76       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
77       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
78       versity of Michigan LDAP 3.3 Release.
79
80
81
82OpenLDAP 2.6.3                    2022/07/14                      LDAP_OPEN(3)
Impressum