/usr/man/cat.3/ldap_dup.3.Z

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 con-
       current requests on the same connection/session without fear of contam-
       ination.  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  cre-
       ation  functions  including  ldap_open(3),  ldap_init(3), ldap_initial-
       ize(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  per-
       forming  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 appro-
       priate 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 asso-
       ciated  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  Univer-
       sity of Michigan LDAP 3.3 Release.

OpenLDAP 2.4.36                   2013/08/17                      LDAP_OPEN(3)
See also ldap_destroy(3)