LDAP_OPEN(3)						     Library Functions Manual						      LDAP_OPEN(3)

NAME

       ldap_dup, ldap_destroy, - Duplicate and destroy LDAP session handles

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

       #include <ldap.h>

       LDAP *ldap_dup(
	      LDAP *old );

       int ldap_destroy(
	      LDAP *old );

DESCRIPTION

       ldap_dup()  duplicates an existing LDAP (LDAP *) session handle.  The new session handle may be used concurrently with the original session
       handle.	In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear  of  con-
       tamination.  Each session handle manages its own private error results.

       ldap_destroy() destroys an existing session handle.

       The ldap_dup() and ldap_destroy() functions are used in conjunction with a "thread safe" version of libldap (libldap_r) to enable operation
       thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling.

       When a session is created through the use of one of the session creation functions including ldap_open(3), ldap_init(3), ldap_initialize(3)
       or  ldap_init_fd(3) an LDAP * session handle is returned to the application.  The session handle may be shared amongst threads, however the
       error codes are unique to a session handle.  Multiple threads performing different operations using the same session handle will result	in
       inconsistent error codes and return values.

       To  prevent  this  confusion,  ldap_dup()  is used duplicate an existing session handle so that multiple threads can share the session, and
       maintain consistent error information and results.

       The message queues for a session are shared between sibling session handles.  Results of operations on a sibling session handles are acces-
       sible  to all the sibling session handles.  Applications desiring results associated with a specific operation should provide the appropri-
       ate msgid to ldap_result().  Applications should avoid calling ldap_result() with LDAP_RES_ANY as that may "steal" and  return  results	in
       the calling thread that another operation in a different thread, using a different session handle, may require to complete.

       When ldap_unbind() is called on a session handle with siblings, all the siblings become invalid.

       Siblings  must  be  destroyed  using ldap_destroy().  Session handle resources associated with the original (LDAP *) will be freed when the
       last session handle is destroyed or when ldap_unbind() is called, if no other session handles currently exist.

ERRORS

       If an error occurs, ldap_dup() will return NULL and errno should be set appropriately.  ldap_destroy() will directly return the	LDAP  code
       associated to the error (or LDAP_SUCCESS in case of success); errno should be set as well whenever appropriate.

SEE ALSO

       ldap_open(3), ldap_init(3), ldap_initialize(3), ldap_init_fd(3), errno(3)

ACKNOWLEDGEMENTS

       This  work  is  based  on  the  previously  proposed LDAP C API Concurrency Extensions draft (draft-zeilenga-ldap-c-api-concurrency-00.txt)
       effort.	OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.  OpenLDAP  Software  is  derived
       from University of Michigan LDAP 3.3 Release.

OpenLDAP							    2012/04/23							      LDAP_OPEN(3)