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 (libldap_r) to enable operation
31       thread  safe  API calls, so that a single session may be simultaneously
32       used across 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
49       results  associated with a specific operation should provide the appro‐
50       priate msgid  to  ldap_result().   Applications  should  avoid  calling
51       ldap_result()  with LDAP_RES_ANY as that may "steal" and return results
52       in the calling thread that another operation  in  a  different  thread,
53       using a 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
59       resources  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),
71       errno(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.4.47                   2018/12/19                      LDAP_OPEN(3)
Impressum