ldap_dup - Duplicate and destroy LDAP session handles
#include <ldap.h> LDAP *ldap_dup( LDAP *old ); int ldap_destroy( LDAP *old );
LDAP_OPEN(3oldap) LDAP_OPEN(3oldap)
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.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------------------+
|Availability | system/network/ldap/openldap |
+---------------+------------------------------+
|Stability | Pass-through uncommitted |
+---------------+------------------------------+
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 the Uni-
versity of Michigan LDAP 3.3 Release.
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from ftp://ftp.openldap.org/pub/OpenLDAP/openl-
dap-release/openldap-2.4.59.tgz.
Further information about this software can be found on the open source
community website at http://www.openldap.org/.
OpenLDAP 2.4.59 2021/06/03 LDAP_OPEN(3oldap)