Man Pages

ldap_destroy(3) - phpMan ldap_destroy(3) - phpMan

Command: man perldoc info search(apropos)  


LDAP_OPEN(3)                                                      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 concur-
       rently with the original session handle.  In a threaded environment, different threads may  execute  concurrent
       requests  on  the  same  connection/session without fear of contamination.  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.  Mul-
       tiple  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 sib-
       ling session handles are accessible to all the sibling session handles.  Applications desiring results  associ-
       ated  with  a  specific  operation  should provide the appropriate 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 2.4.40                   2014/09/20                      LDAP_OPEN(3)