|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ERRORS | SEE ALSO | ACKNOWLEDGEMENTS | COLOPHON |
|
|
|
LDAP_OPEN(3) 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.
This page is part of the OpenLDAP (an open source implementation
of the Lightweight Directory Access Protocol) project.
Information about the project can be found at
⟨http://www.openldap.org/⟩. If you have a bug report for this
manual page, see ⟨http://www.openldap.org/its/⟩. This page was
obtained from the project's upstream Git repository
⟨https://git.openldap.org/openldap/openldap.git⟩ on 2024-06-14.
(At that time, the date of the most recent commit that was found
in the repository was 2024-06-13.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
OpenLDAP LDVERSION RELEASEDATE LDAP_OPEN(3)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|