1 INTERNET-DRAFT Kurt D. Zeilenga
2 Intended Category: Standards Track OpenLDAP Foundation
3 Extends: draft-ietf-ldapext-ldap-c-api-03.txt
7 LDAP C API Concurrency Extensions
8 <draft-zeilenga-ldap-c-api-concurrency-00.txt>
10 1. Status of this Memo
12 This document is an Internet-Draft and is in full conformance with all
13 provisions of Section 10 of RFC2026.
15 This draft document will be submitted to the RFC Editor as a Standards
16 Track document. Distribution of this memo is unlimited. Technical
17 discussion of this document will take place on the IETF LDAP Extension
18 Working Group mailing list <ietf-ldapext@netscape.com>. Please send
19 editorial comments directly to the author <Kurt@OpenLDAP.org>.
21 Internet-Drafts are working documents of the Internet Engineering Task
22 Force (IETF), its areas, and its working groups. Note that other
23 groups may also distribute working documents as Internet-Drafts.
25 Internet-Drafts are draft documents valid for a maximum of six months
26 and may be updated, replaced, or obsoleted by other documents at any
27 time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
30 The list of current Internet-Drafts can be accessed at
31 http://www.ietf.org/ietf/1id-abstracts.txt
33 The list of Internet-Draft Shadow Directories can be accessed at
34 http://www.ietf.org/shadow.html.
36 Copyright 1999, The Internet Society. All Rights Reserved.
38 Please see the Copyright section near the end of this document for
43 This document defines extensions to the LDAP C API to support use in
44 concurrent execution environments. The document describes and defines
48 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
50 requirements for multiple concurrency levels: thread safe, session
51 thread safe, and operation thread safe.
53 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
54 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
55 to be interpreted as described in RFC 2119 [KEYW].
59 This document extends the LDAP C API [CAPI] specification to support
60 use in concurrent execution environments. The extensions add powerful
61 concurrent processing capabilities to the simple to use CAPI. This
62 document provides an overview of different levels of concurrent
63 execution support and offers a number of CAPI "features" to provide
64 capabilities at these levels.
66 The remainder of this section describes three levels of concurrent
67 execution: thread safe, session thread safe, operation thread safe
72 An implementation which allows applications to safely execute in
73 concurrent execution environments where the application provides
74 necessary synchronization to ensure serialization of CAPI usage is
75 considered to be "thread safe." Applications may execute non-CAPI
76 calls in concurrent execution contexts when using thread safe
79 3.2. Session Thread Safe
81 A "thread safe" implementation which allows CAPI calls associated with
82 different LDAP sessions to proceed asychronously is considered to be
83 "session thread safe."
85 3.3. Operation Thread Safe
87 A "session thread safe" implementation which allows CAPI calls
88 associated with different LDAP operations to proceed asychronously is
89 considered to be "operation thread safe".
91 4. Basic Thread Safe Feature
95 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
97 This section details requirements for the thread safe CAPI feature.
98 Implementations fulfilling these requirements are said to support the
99 LDAP_API_FEATURE_THREAD_SAFE feature and SHOULD advertise this support
100 as detailed below. This feature SHOULD be provided by
103 Implementations of this feature MUST implement the LDAP error handling
106 Implementations of this feature MUST allow non-CAPI calls to proceed
109 Implementations of this feature MUST NOT use any non-thread safe call
110 or mechanism provided by C environment or operating system. An
111 example of non-reentrant calls is the UNIX strtok() function. Example
112 of a non-reentrant mechanism is global (i.e.: non-thread specific)
115 5. Session Thread Safe Feature
117 This section details requirements for the session thread safe CAPI
118 feature. Implementations fulfilling these requirements are said to
119 support the LDAP_API_FEATURE_SESSION_THREAD_SAFE feature and SHOULD
120 advertise this support as detailed below. This feature is
123 5.1. Prerequisite Features
125 Implementations providing this feature MUST provide and advertise both
126 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO] and
127 LDAP_API_FEATURE_THREAD_SAFE.
129 5.2. Atomic Session Handles
131 Implementations providing this feature SHOULD ensure that operations
132 upon a given session handle are atomic. Implementations which provide
133 atomic session handles SHOULD advertise the feature
134 LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES.
136 5.3. Concurrency Requirements
138 Implementations providing this feature MUST not restrict CAPI calls
139 acting upon a given LDAP session to a particular execution context.
140 Applications MAY use a session handle on any thread. Applications
144 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
146 MUST NOT assume that operations upon a session are atomic.
148 Implementations providing this feature MUST allow CAPI calls acting
149 upon different LDAP sessions to safely proceed asynchronously.
151 Implementations providing this feature MUST allow CAPI calls not
152 acting upon an LDAP session to safely proceed asynchronously.
154 6. Operation Thread Safe Feature
156 This section details requirements for the operation thread safe CAPI
157 feature based upon a duplicate session handles mechanism.
159 Implementations fulfilling these requirements are said to support the
160 LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES feature and SHOULD
161 advertise this support as detailed below. This feature is OPTIONAL.
163 6.1. Prerequisite Features
165 Implementations of this feature MUST provide and advertise
166 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO],
167 LDAP_API_FEATURE_THREAD_SAFE, LDAP_API_FEATURE_SESSION_THREAD_SAFE,
168 and LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES.
170 6.2. Duplicated Session Handles
172 Implementations of this feature MUST support duplicated session
175 As defined in CAPI, a session handle refers to an LDAP session
176 encompassing connections with one or more servers, associated message
177 results, a set of properties (options), and state information. This
178 feature provides a mechanism for a handle to be duplicated. A session
179 handle and its duplicates are considered siblings. Each sibling
180 session handle refers to the same LDAP session and message results.
181 Some properties and state are specific to a handle and others shared
182 between siblings as detailed below.
184 CAPI calls made on a handle are atomic. Calls made on sibling (or
185 other) handles MAY proceed asynchronously.
187 Session handles are duplicated using ldap_dup() and destroyed using
188 ldap_destroy(). Use of duplicated session handles with CAPI calls
189 have the following semantics detailed in the sections below.
193 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
195 6.2.1. Creating and Destroying duplicated sessions
197 Implementations of this feature are required to provide two new
198 routines: LDAP *ldap_dup( ld ); int ldap_destroy( ld );
200 Parameters are: ld The session handle
202 The ldap_dup() function returns a duplicate of a session handle. The
203 returned session handle may be used concurrently with the original
204 session handle as described below. ldap_dup returns NULL if it is not
205 able to duplicate the session handle and sets LDAP_OPT_ERROR_NUMBER
206 and ldap_errno indicating the nature of the failure.
208 The ldap_destroy() function destroys the session handle. If the
209 session handle has no siblings, ldap_destroy behaves exactly like
210 ldap_unbind. If the session handle has siblings, the resources
211 assocated with the handle are released and the siblings remain valid.
212 ldap_destroy() returns LDAP_SUCCESS or an error number indicating the
213 nature of failure. Regardless of returned value, the handle SHOULD be
214 considered invalid and MUST not be used in subsequent calls. Attempts
215 to use a destroyed session handle MUST NOT result in
216 LDAP_INVALID_SESSION error being reported. Implementations SHOULD
217 report LDAP_PARAM_ERROR in such cases.
219 6.2.2. ldap_unbind and siblings
221 When ldap_unbind() is called on a session handle with siblings, the
222 siblings become invalid. The siblings must be destroyed using
223 ldap_destroy(). All attempts to obtain the siblings'
224 LDAP_OPT_ERROR_NUMBER will return LDAP_INVALID_SESSION. Any use other
225 than ldap_destroy() or reading LDAP_OPT_ERROR_NUMBER will fail with an
226 LDAP_INVALID_SESSION error being reported.
230 Message queues are shared between siblings. Results of operations on
231 a duplicated session handles are accessible to all sibling session
234 Applications desiring results associated with a specific operation
235 SHOULD provide the appropriate msgid to ldap_result(). Applications
236 SHOULD avoid calling ldap_result() with LDAP_RES_ANY as such may
237 "steal" and return results which an operation on a sibling requires to
242 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
244 6.2.4. Session Options
246 The following CAPI options access values shared between siblings:
248 LDAP_OPT_API_INFO LDAP_OPT_DESC LDAP_OPT_REFERRALS
249 LDAP_OPT_PROTOCOL_VERSION LDAP_OPT_API_FEATURE_INFO
252 The following CAPI options access values specific to a sibling:
254 LDAP_OPT_DEREF LDAP_OPT_SIZELIMIT LDAP_OPT_TIMELIMIT
255 LDAP_OPT_RESTART LDAP_OPT_CLIENT_CONTROLS
256 LDAP_OPT_SERVER_CONTROLS LDAP_OPT_ERROR_NUMBER
257 LDAP_OPT_ERROR_STRING LDAP_OPT_MATCHED_DN
259 6.2.4.1. LDAP_OPT_SESSION_REFCNT
261 In addition, implementations MUST provide the READ-ONLY, shared
262 LDAP_OPT_SESSION_REFCNT option. LDAP_OPT_SESSION_REFCNT returns the
263 reference count associated with the supplied session handle argument.
264 The session handle argument is required. The outvalue argument should
265 be a pointer to an integer. Example use:
267 int refcount(LDAP *ld) {
269 #ifdef LDAP_OPT_SESSION_REFCNT
273 rc = ldap_get_option(ld,
274 LDAP_OPT_SESSION_REFCNT, &refcnt);
276 if(rc == LDAP_OPT_SUCCESS) {
286 7. Advertising Features
288 This document REQUIRES that supported features with the name in the
289 form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as
293 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
297 SHOULD provide the macro LDAP_API_FEATURE_x with the value
298 of 1000 + revision number of this draft (i.e.: 1000+0 for
299 this 0 revision of the draft).
301 MUST provide the CAPI extension "x" when returning API
302 information upon LDAP_OPT_API_INFO option access, and
304 MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO
305 option mechanism. The feature version provided MUST match
306 the value LDAP_API_FEATURE_x macro
308 where x is replaced appropriately.
310 As implementations may not provide macros for all features,
311 applications SHOULD use LDAP_OPT_API_INFO to determine which features
312 are provided by a given implementation.
314 8. Changes to the C API specification
318 This extension introduces the following macros:
320 LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES
321 LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES
322 LDAP_API_FEATURE_SESSION_THREAD_SAFE
323 LDAP_API_FEATURE_THREAD_SAFE
324 LDAP_API_FEATURE_OPERATION_THREAD_SAFE LDAP_INVALID_SESSION
325 LDAP_OPT_SESSION_REFCNT
327 This extension introduces these new functions:
329 ldap_destroy() ldap_dup()
331 This extension introduces no new typedefs nor structure names.
333 8.2. Duplicated Session Handles
335 This extension introduces duplicated session handles and requirements
336 for handling duplicated session handles. Semantics of non-duplicated
337 session handles are not affected by this introduction. However, the
338 semantics of calls upon duplicate session handles differs as described
343 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
345 9. Security Considerations
347 None taken, none given.
351 Copyright 1999, The Internet Society. All Rights Reserved.
353 This document and translations of it may be copied and furnished to
354 others, and derivative works that comment on or otherwise explain it
355 or assist in its implementation may be prepared, copied, published and
356 distributed, in whole or in part, without restriction of any kind,
357 provided that the above copyright notice and this paragraph are
358 included on all such copies and derivative works. However, this
359 document itself may not be modified in any way, such as by removing
360 the copyright notice or references to the Internet Society or other
361 Internet organizations, except as needed for the purpose of
362 developing Internet standards in which case the procedures for
363 copyrights defined in the Internet Standards process must be followed,
364 or as required to translate it into languages other than English.
366 The limited permissions granted above are perpetual and will not be
367 revoked by the Internet Society or its successors or assigns.
369 This document and the information contained herein is provided on an
370 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
371 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
372 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
373 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
374 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
378 [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The
379 C LDAP Application Program Interface", INTERNET-DRAFT, <draft-
380 ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions, June 1999.
382 [ERRNO] K. Zeilenga, "LDAP C API Error Reporting Extension",
383 INTERNET-DRAFT, <draft-zeilenga-ldap-c-api-errno-00.txt>,
386 [KEYW] S. Bradner, "Key words for use in RFCs to Indicate
387 Requirement Levels", RFC 2119, March 1997.
391 INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999
393 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
394 Access Protocol (v3)", RFC 2251, December 1997.
402 This document expires on 28 March 2000.
406 ---------------------------------------------------------------------
408 INTERNET-DRAFT Kurt D. Zeilenga
409 Intended Category: Standards Track OpenLDAP Foundation
410 Extends: draft-ietf-ldapext-ldap-c-api-03.txt
411 Expires: 28 March 2000
414 LDAP C API Error Reporting Extension
415 <draft-zeilenga-ldap-c-api-errno-00.txt>
417 1. Status of this Memo
419 This document is an Internet-Draft and is in full conformance with all
420 provisions of Section 10 of RFC2026.
422 This draft document will be submitted to the RFC Editor as a Standards
423 Track document. Distribution of this memo is unlimited. Technical
424 discussion of this document will take place on the IETF LDAP Extension
425 Working Group mailing list <ietf-ldapext@netscape.com>. Please send
426 editorial comments directly to the author <Kurt@OpenLDAP.org>.
428 Internet-Drafts are working documents of the Internet Engineering Task
429 Force (IETF), its areas, and its working groups. Note that other
430 groups may also distribute working documents as Internet-Drafts.
432 Internet-Drafts are draft documents valid for a maximum of six months
433 and may be updated, replaced, or obsoleted by other documents at any
434 time. It is inappropriate to use Internet-Drafts as reference
435 material or to cite them other than as ``work in progress.''
437 The list of current Internet-Drafts can be accessed at
438 http://www.ietf.org/ietf/1id-abstracts.txt
440 The list of Internet-Draft Shadow Directories can be accessed at
441 http://www.ietf.org/shadow.html.
443 Copyright 1999, The Internet Society. All Rights Reserved.
445 Please see the Copyright section near the end of this document for
450 This document defines a manatory extension to the LDAP C API to
451 provide error reporting for all API calls. The mechanism is
452 nonintrusive and can, optionally, support concurrent execution
457 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
459 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL
460 NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', and ``MAY'' in
461 this document are to be interpreted as described in RFC 2119 [KEYW].
463 3. Background and Intent of Use
465 The LDAP [LDAP] C API [CAPI] provides an interface which (due to
466 legacy compatibiity issues) does not provide a consistent mechanism
467 for reporting errors. A large number of the calls within the
468 specification have no mechanism to indicate the nature of a failure.
469 The usefulness of a CAPI without a consistent, easy to use, error
470 reporting mechanism is limited.
472 This document defines an mandatory extension to the CAPI. All
473 implementations of the CAPI MUST provide this extension.
475 The extension details additional requirements for error reporting.
476 Implementations MUST fulfill all other CAPI error reporting
479 4. Error Handling Extension
481 This extension provides a mechanism that applications MAY use to
482 obtain an LDAP error number indicating the nature of the failure
483 associated with the last failed CAPI call.
485 Implementations MUST provide access to an LDAP error number (CAPI,
486 Section 9) resulting from the last failed CAPI call via the symbol
487 ldap_errno. The last failed CAPI call may be within the global
488 context or within the current execution context.
490 The ldap_errno MUST evaluate to a modifiable lvalue that has type
491 'int', the value of which is set to a LDAP error number. It is
492 unspecified whether ldap_errno is a macro or an identifier declared
493 with external linkage. If a macro definition is suppressed in order
494 to access an actual object, or a program defines an identifier with
495 the name ldap_errno, the behavior is undefined.
497 Applications MUST access ldap_errno within the same concurrent
498 execution context, commonly a thread, in which the failure occurred.
499 The value of ldap_errno is LDAP_SUCCESS (0) if no API failure has
500 occurred within the supported context and the user has not assigned a
501 value within the supported context.
505 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
507 Implementations SHALL NOT update the ldap_errno value upon successful
508 CAPI call completion.
510 Implementations providing a current execution context specific
511 ldap_errno MUST advertise the feature LDAP_API_CONTEXT_SPECIFIC_ERRNO
512 as described in Section 6. Implementation of
513 LDAP_API_CONTEXT_SPECIFIC_ERRNO is RECOMMENDED.
515 4.1. Reporting Server Errors
517 It is not a CAPI failure for a server to return an error number.
518 Implementations SHALL NOT assign error results returned by servers to
521 4.2. Implementation Specific Reporting
523 The CAPI specification stated that the caller may obtain an indication
524 of failure of certain calls (see listed below) using implementation
525 specific and/or operating system specific requirements.
526 Implementations are NOT REQUIRED to support any implementation
527 specific and/or operating system mechanism for ANY call detailed by
528 the CAPI specification or its extensions.
530 Affected calls include ldap_init(), ldap_open(), and ber_*().
534 The following is an example showing how an application may obtain the
535 error information resulting from a failed CAPI calls:
538 LDAP *ld = ldap_init("localhost", 389);
541 printf("ldap_init failed, ldap_errno=%d (%s)\n",
542 ldap_errno, ldap_err2string(ldap_errno));
544 printf("unable to initialize LDAP session\n");
548 msgid = ldap_simple_bind(ld, NULL, NULL);
551 int err = ldap_errno;
553 if (err != LDAP_SUCCESS ) {
557 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
560 printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n",
561 err, ldap_err2string(err));
566 printf("ldap_simple_bind failed\n");
568 rc = ldap_get_option(ld,
569 LDAP_OPT_ERROR_NUMBER, &lderr);
571 if(rc == LDAP_OPT_SUCCESS) {
572 printf(" reason=%d (%s)\n",
573 lderr, ldap_err2string(lderr));
576 printf("ldap_get_option failed, ldap_errno=%d (%s)\n",
577 ldap_errno, ldap_err2string(ldap_errno)); }
585 unbind: if(ldap_unbind(ld) != 0) {
586 printf("ldap_unbind failed, ldap_errno=%d (%s)\n",
587 ldap_errno, ldap_error2str(ldap_errno));
593 5. Advertising Features
595 This document REQUIRES that supported features with the name in the
596 form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as
599 SHOULD provide the macro LDAP_API_FEATURE_x with the value
600 of 1000 + revision number of this draft (i.e.: 1000+0 for
601 this 0 revision of the draft).
603 MUST provide the CAPI extension "x" when returning API
604 information upon LDAP_OPT_API_INFO option access, and
608 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
610 MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO
611 option mechanism. The feature version provided MUST match
612 the value LDAP_API_FEATURE_x macro
614 where x is replaced appropriately.
616 As implementations may not provide macros for all features,
617 applications SHOULD use LDAP_OPT_API_INFO to determine which features
618 are provided by a given implementation.
620 6. Changes to the LDAP C API
622 This section provides a summary of changes to the CAPI specification.
624 6.1. LDAP_API_VERSION
626 LDAP_API_VERSION should be set to the RFC number of this extension if
627 and when it is published as a Standards Track RFC. (see purpose of
630 Until such time as this document is published as an RFC,
631 implementations should use the value specified by CAPI plus 100 + 10 *
632 the number of this draft.
634 For the third draft of CAPI and this 0 revision of draft, the value of
635 2103 ((2000+3) + (100+10*0)) should be used.
639 This extension introduces two new symbols:
640 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO ldap_errno
642 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro. ldap_errno MAY be
645 This extension indroductes no new functions, typedefs, or structure
648 6.3. Implementation/System Specific Error Handling
650 This extensions removes any requirements that implementations to use
651 implementation and/or operating system specific error reporting
656 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
658 7. Security Considerations
660 None taken, none given.
664 Copyright 1999, The Internet Society. All Rights Reserved.
666 This document and translations of it may be copied and furnished to
667 others, and derivative works that comment on or otherwise explain it
668 or assist in its implementation may be prepared, copied, published and
669 distributed, in whole or in part, without restriction of any kind,
670 provided that the above copyright notice and this paragraph are
671 included on all such copies and derivative works. However, this
672 document itself may not be modified in any way, such as by removing
673 the copyright notice or references to the Internet Society or other
674 Internet organizations, except as needed for the purpose of
675 developing Internet standards in which case the procedures for
676 copyrights defined in the Internet Standards process must be followed,
677 or as required to translate it into languages other than English.
679 The limited permissions granted above are perpetual and will not be
680 revoked by the Internet Society or its successors or assigns.
682 This document and the information contained herein is provided on an
683 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
684 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
685 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
686 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
687 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
691 [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha,
692 "The C LDAP Application Program Interface", INTERNET-DRAFT,
693 <draft-ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions,
696 [KEYW] S. Bradner, "Key words for use in RFCs to Indicate
697 Requirement Levels", RFC 2119, March 1997.
699 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
700 Access Protocol (v3)", RFC 2251, December 1997.
704 INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999
712 This document expires on 28 March 2000.