From 5ea77a75dd2d2158401331879f3c8f47940a732c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:35:32 +0200 Subject: Adding upstream version 2.5.13+dfsg. Signed-off-by: Daniel Baumann --- doc/man/man3/ldap_dup.3 | 125 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 doc/man/man3/ldap_dup.3 (limited to 'doc/man/man3/ldap_dup.3') diff --git a/doc/man/man3/ldap_dup.3 b/doc/man/man3/ldap_dup.3 new file mode 100644 index 0000000..945ca54 --- /dev/null +++ b/doc/man/man3/ldap_dup.3 @@ -0,0 +1,125 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +LDAP *ldap_dup( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.LP +.ft B +int ldap_destroy( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.SH DESCRIPTION +.LP +.B ldap_dup() +duplicates an existing LDAP +.RB ( "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. +.LP +.B ldap_destroy() +destroys an existing session handle. +.LP +The +.B ldap_dup() +and +.B ldap_destroy() +functions are used in conjunction with a "thread safe" version +of +.B libldap +to enable operation thread safe API calls, so that a single session +may be simultaneously used across multiple threads with consistent +error handling. +.LP +When a session is created through the use of one of the session creation +functions including +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3) +or +.BR ldap_init_fd (3) +an +.B "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. +.LP +To prevent this confusion, +.B ldap_dup() +is used duplicate an existing session handle so that multiple threads +can share the session, and maintain consistent error information +and results. +.LP +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 +.BR ldap_result() . +Applications should avoid calling +.B ldap_result() +with +.B 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. +.LP +When +.B ldap_unbind() +is called on a session handle with siblings, all the +siblings become invalid. +.LP +Siblings must be destroyed using +.BR ldap_destroy() . +Session handle resources associated with the original +.RB ( "LDAP *" ) +will be freed when the last session handle is destroyed or when +.B ldap_unbind() +is called, if no other session handles currently exist. +.SH ERRORS +If an error occurs, +.B ldap_dup() +will return NULL and +.I errno +should be set appropriately. +.B ldap_destroy() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +.I errno +should be set as well whenever appropriate. +.SH SEE ALSO +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3), +.BR ldap_init_fd (3), +.BR errno (3) +.SH ACKNOWLEDGEMENTS +This work is based on the previously proposed +.B LDAP C API Concurrency Extensions +draft +.BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) +effort. +.so ../Project -- cgit v1.2.3