git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_dup.3

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