GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
LDAP_OPEN(3) FreeBSD Library Functions Manual LDAP_OPEN(3)

ldap_dup, ldap_destroy, - Duplicate and destroy LDAP session handles

OpenLDAP LDAP (libldap, -lldap)

#include <ldap.h>
LDAP *ldap_dup(
LDAP *old );
int ldap_destroy(
LDAP *old );

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 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 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 accessible to all the sibling session handles. Applications desiring results associated 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.

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.

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

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 the University of Michigan LDAP 3.3 Release.
2022/05/04 OpenLDAP 2.5.12

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.