1.lf 1 stdin 2.TH LDAP_OPEN 3 "2020/04/28" "OpenLDAP 2.4.50" 3.\" $OpenLDAP$ 4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved. 5.\" Copying restrictions apply. See COPYRIGHT/LICENSE. 6.SH NAME 7ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles 8.SH LIBRARY 9OpenLDAP LDAP (libldap, \-lldap) 10.SH SYNOPSIS 11.nf 12.ft B 13#include <ldap.h> 14.LP 15.ft B 16LDAP *ldap_dup( 17.RS 18.ft B 19LDAP *\fIold\fB ); 20.RE 21.LP 22.ft B 23int ldap_destroy( 24.RS 25.ft B 26LDAP *\fIold\fB ); 27.RE 28.SH DESCRIPTION 29.LP 30.B ldap_dup() 31duplicates an existing LDAP 32.RB ( "LDAP *" ) 33session handle. 34The new session handle may be used concurrently with the 35original session handle. 36In a threaded environment, different threads may execute concurrent 37requests on the same connection/session without fear of contamination. 38Each session handle manages its own private error results. 39.LP 40.B ldap_destroy() 41destroys an existing session handle. 42.LP 43The 44.B ldap_dup() 45and 46.B ldap_destroy() 47functions are used in conjunction with a "thread safe" version 48of 49.B libldap 50.RB ( libldap_r ) 51to enable operation thread safe API calls, so that a single session 52may be simultaneously used across multiple threads with consistent 53error handling. 54.LP 55When a session is created through the use of one of the session creation 56functions including 57.BR ldap_open (3), 58.BR ldap_init (3), 59.BR ldap_initialize (3) 60or 61.BR ldap_init_fd (3) 62an 63.B "LDAP *" 64session handle is returned to the application. 65The session handle may be shared amongst threads, however the 66error codes are unique to a session handle. 67Multiple threads performing different operations using the same 68session handle will result in inconsistent error codes and 69return values. 70.LP 71To prevent this confusion, 72.B ldap_dup() 73is used duplicate an existing session handle so that multiple threads 74can share the session, and maintain consistent error information 75and results. 76.LP 77The message queues for a session are shared between sibling session handles. 78Results of operations on a sibling session handles are accessible 79to all the sibling session handles. 80Applications desiring results associated with a specific operation 81should provide the appropriate msgid to 82.BR ldap_result() . 83Applications should avoid calling 84.B ldap_result() 85with 86.B LDAP_RES_ANY 87as that may "steal" and return results in the calling thread 88that another operation in a different thread, using a 89different session handle, may require to complete. 90.LP 91When 92.B ldap_unbind() 93is called on a session handle with siblings, all the 94siblings become invalid. 95.LP 96Siblings must be destroyed using 97.BR ldap_destroy() . 98Session handle resources associated with the original 99.RB ( "LDAP *" ) 100will be freed when the last session handle is destroyed or when 101.B ldap_unbind() 102is called, if no other session handles currently exist. 103.SH ERRORS 104If an error occurs, 105.B ldap_dup() 106will return NULL and 107.I errno 108should be set appropriately. 109.B ldap_destroy() 110will directly return the LDAP code associated to the error (or 111.I LDAP_SUCCESS 112in case of success); 113.I errno 114should be set as well whenever appropriate. 115.SH SEE ALSO 116.BR ldap_open (3), 117.BR ldap_init (3), 118.BR ldap_initialize (3), 119.BR ldap_init_fd (3), 120.BR errno (3) 121.SH ACKNOWLEDGEMENTS 122This work is based on the previously proposed 123.B LDAP C API Concurrency Extensions 124draft 125.BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) 126effort. 127.lf 1 ./../Project 128.\" Shared Project Acknowledgement Text 129.B "OpenLDAP Software" 130is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. 131.B "OpenLDAP Software" 132is derived from the University of Michigan LDAP 3.3 Release. 133.lf 127 stdin 134