idnits 2.17.1 draft-zeilenga-ldap-c-api-concurrency-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == Mismatching filename: the document gives the document name as 'draft-ietf-ldapext-ldap-c-api-03', but the file name used is 'draft-zeilenga-ldap-c-api-concurrency-00' == It seems as if not all pages are separated by form feeds - found 0 form feeds but 16 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([KEYW]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 89: '...SAFE feature and SHOULD advertise this...' RFC 2119 keyword, line 90: '...w. This feature SHOULD be provided by...' RFC 2119 keyword, line 93: '... of this feature MUST implement the LD...' RFC 2119 keyword, line 96: '... of this feature MUST allow non-CAPI c...' RFC 2119 keyword, line 99: '... of this feature MUST NOT use any non-...' (44 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 329 has weird spacing: '...for the purpo...' == Line 613 has weird spacing: '...for the purpo...' -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Implementations providing this feature MUST not restrict CAPI calls acting upon a given LDAP session to a particular execution context. Applications MAY use a session handle on any thread. Applications MUST NOT assume that operations upon a session are atomic. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The ldap_destroy() function destroys the session handle. If the session handle has no siblings, ldap_destroy behaves exactly like ldap_unbind. If the session handle has siblings, the resources assocated with the handle are released and the siblings remain valid. ldap_destroy() returns LDAP_SUCCESS or an error number indicating the nature of failure. Regardless of returned value, the handle SHOULD be considered invalid and MUST not be used in subsequent calls. Attempts to use a destroyed session handle MUST NOT result in LDAP_INVALID_SESSION error being reported. Implementations SHOULD report LDAP_PARAM_ERROR in such cases. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (28 September 1999) is 8967 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'KEYW' on line 635 looks like a reference -- Missing reference section? 'CAPI' on line 630 looks like a reference -- Missing reference section? 'ERRNO' on line 350 looks like a reference -- Missing reference section? 'LDAP' on line 638 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 6 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Kurt D. Zeilenga 2 Intended Category: Standards Track OpenLDAP Foundation 3 Extends: draft-ietf-ldapext-ldap-c-api-03.txt 4 Expires: 28 March 2000 5 28 September 1999 7 LDAP C API Concurrency Extensions 8 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 . Please send 19 editorial comments directly to the author . 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 39 more information. 41 2. Abstract 43 This document defines extensions to the LDAP C API to support use in 44 concurrent execution environments. The document describes and defines 45 requirements for multiple concurrency levels: thread safe, session 46 thread safe, and operation thread safe. 48 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 49 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 50 to be interpreted as described in RFC 2119 [KEYW]. 52 3. Introduction 54 This document extends the LDAP C API [CAPI] specification to support 55 use in concurrent execution environments. The extensions add powerful 56 concurrent processing capabilities to the simple to use CAPI. This 57 document provides an overview of different levels of concurrent 58 execution support and offers a number of CAPI "features" to provide 59 capabilities at these levels. 61 The remainder of this section describes three levels of concurrent 62 execution: thread safe, session thread safe, operation thread safe 63 APIs. 65 3.1. Thread Safe 67 An implementation which allows applications to safely execute in 68 concurrent execution environments where the application provides 69 necessary synchronization to ensure serialization of CAPI usage is 70 considered to be "thread safe." Applications may execute non-CAPI 71 calls in concurrent execution contexts when using thread safe 72 implementations. 74 3.2. Session Thread Safe 76 A "thread safe" implementation which allows CAPI calls associated with 77 different LDAP sessions to proceed asychronously is considered to be 78 "session thread safe." 80 3.3. Operation Thread Safe 82 A "session thread safe" implementation which allows CAPI calls 83 associated with different LDAP operations to proceed asychronously is 84 considered to be "operation thread safe". 86 4. Basic Thread Safe Feature 87 This section details requirements for the thread safe CAPI feature. 88 Implementations fulfilling these requirements are said to support the 89 LDAP_API_FEATURE_THREAD_SAFE feature and SHOULD advertise this support 90 as detailed below. This feature SHOULD be provided by 91 implementations. 93 Implementations of this feature MUST implement the LDAP error handling 94 extension [ERRNO]. 96 Implementations of this feature MUST allow non-CAPI calls to proceed 97 asynchronously. 99 Implementations of this feature MUST NOT use any non-thread safe call 100 or mechanism provided by C environment or operating system. An 101 example of non-reentrant calls is the UNIX strtok() function. Example 102 of a non-reentrant mechanism is global (i.e.: non-thread specific) 103 errno. 105 5. Session Thread Safe Feature 107 This section details requirements for the session thread safe CAPI 108 feature. Implementations fulfilling these requirements are said to 109 support the LDAP_API_FEATURE_SESSION_THREAD_SAFE feature and SHOULD 110 advertise this support as detailed below. This feature is 111 RECOMMENDED. 113 5.1. Prerequisite Features 115 Implementations providing this feature MUST provide and advertise both 116 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO] and 117 LDAP_API_FEATURE_THREAD_SAFE. 119 5.2. Atomic Session Handles 121 Implementations providing this feature SHOULD ensure that operations 122 upon a given session handle are atomic. Implementations which provide 123 atomic session handles SHOULD advertise the feature 124 LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES. 126 5.3. Concurrency Requirements 128 Implementations providing this feature MUST not restrict CAPI calls 129 acting upon a given LDAP session to a particular execution context. 130 Applications MAY use a session handle on any thread. Applications 131 MUST NOT assume that operations upon a session are atomic. 133 Implementations providing this feature MUST allow CAPI calls acting 134 upon different LDAP sessions to safely proceed asynchronously. 136 Implementations providing this feature MUST allow CAPI calls not 137 acting upon an LDAP session to safely proceed asynchronously. 139 6. Operation Thread Safe Feature 141 This section details requirements for the operation thread safe CAPI 142 feature based upon a duplicate session handles mechanism. 144 Implementations fulfilling these requirements are said to support the 145 LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES feature and SHOULD 146 advertise this support as detailed below. This feature is OPTIONAL. 148 6.1. Prerequisite Features 150 Implementations of this feature MUST provide and advertise 151 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO], 152 LDAP_API_FEATURE_THREAD_SAFE, LDAP_API_FEATURE_SESSION_THREAD_SAFE, 153 and LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES. 155 6.2. Duplicated Session Handles 157 Implementations of this feature MUST support duplicated session 158 handles. 160 As defined in CAPI, a session handle refers to an LDAP session 161 encompassing connections with one or more servers, associated message 162 results, a set of properties (options), and state information. This 163 feature provides a mechanism for a handle to be duplicated. A session 164 handle and its duplicates are considered siblings. Each sibling 165 session handle refers to the same LDAP session and message results. 166 Some properties and state are specific to a handle and others shared 167 between siblings as detailed below. 169 CAPI calls made on a handle are atomic. Calls made on sibling (or 170 other) handles MAY proceed asynchronously. 172 Session handles are duplicated using ldap_dup() and destroyed using 173 ldap_destroy(). Use of duplicated session handles with CAPI calls 174 have the following semantics detailed in the sections below. 176 6.2.1. Creating and Destroying duplicated sessions 178 Implementations of this feature are required to provide two new 179 routines: LDAP *ldap_dup( ld ); int ldap_destroy( ld ); 181 Parameters are: ld The session handle 183 The ldap_dup() function returns a duplicate of a session handle. The 184 returned session handle may be used concurrently with the original 185 session handle as described below. ldap_dup returns NULL if it is not 186 able to duplicate the session handle and sets LDAP_OPT_ERROR_NUMBER 187 and ldap_errno indicating the nature of the failure. 189 The ldap_destroy() function destroys the session handle. If the 190 session handle has no siblings, ldap_destroy behaves exactly like 191 ldap_unbind. If the session handle has siblings, the resources 192 assocated with the handle are released and the siblings remain valid. 193 ldap_destroy() returns LDAP_SUCCESS or an error number indicating the 194 nature of failure. Regardless of returned value, the handle SHOULD be 195 considered invalid and MUST not be used in subsequent calls. Attempts 196 to use a destroyed session handle MUST NOT result in 197 LDAP_INVALID_SESSION error being reported. Implementations SHOULD 198 report LDAP_PARAM_ERROR in such cases. 200 6.2.2. ldap_unbind and siblings 202 When ldap_unbind() is called on a session handle with siblings, the 203 siblings become invalid. The siblings must be destroyed using 204 ldap_destroy(). All attempts to obtain the siblings' 205 LDAP_OPT_ERROR_NUMBER will return LDAP_INVALID_SESSION. Any use other 206 than ldap_destroy() or reading LDAP_OPT_ERROR_NUMBER will fail with an 207 LDAP_INVALID_SESSION error being reported. 209 6.2.3. ldap_result() 211 Message queues are shared between siblings. Results of operations on 212 a duplicated session handles are accessible to all sibling session 213 handles. 215 Applications desiring results associated with a specific operation 216 SHOULD provide the appropriate msgid to ldap_result(). Applications 217 SHOULD avoid calling ldap_result() with LDAP_RES_ANY as such may 218 "steal" and return results which an operation on a sibling requires to 219 complete. 221 6.2.4. Session Options 223 The following CAPI options access values shared between siblings: 225 LDAP_OPT_API_INFO LDAP_OPT_DESC LDAP_OPT_REFERRALS 226 LDAP_OPT_PROTOCOL_VERSION LDAP_OPT_API_FEATURE_INFO 227 LDAP_OPT_HOST_NAME 229 The following CAPI options access values specific to a sibling: 231 LDAP_OPT_DEREF LDAP_OPT_SIZELIMIT LDAP_OPT_TIMELIMIT 232 LDAP_OPT_RESTART LDAP_OPT_CLIENT_CONTROLS 233 LDAP_OPT_SERVER_CONTROLS LDAP_OPT_ERROR_NUMBER 234 LDAP_OPT_ERROR_STRING LDAP_OPT_MATCHED_DN 236 6.2.4.1. LDAP_OPT_SESSION_REFCNT 238 In addition, implementations MUST provide the READ-ONLY, shared 239 LDAP_OPT_SESSION_REFCNT option. LDAP_OPT_SESSION_REFCNT returns the 240 reference count associated with the supplied session handle argument. 241 The session handle argument is required. The outvalue argument should 242 be a pointer to an integer. Example use: 244 int refcount(LDAP *ld) { 246 #ifdef LDAP_OPT_SESSION_REFCNT 248 if(ld != NULL) { 249 int refcnt, rc; 250 rc = ldap_get_option(ld, 251 LDAP_OPT_SESSION_REFCNT, &refcnt); 253 if(rc == LDAP_OPT_SUCCESS) { 254 return refcnt; 255 } 256 } 258 #endif 260 return -1; 261 } 263 7. Advertising Features 265 This document REQUIRES that supported features with the name in the 266 form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as 267 follows: 269 SHOULD provide the macro LDAP_API_FEATURE_x with the value 270 of 1000 + revision number of this draft (i.e.: 1000+0 for 271 this 0 revision of the draft). 273 MUST provide the CAPI extension "x" when returning API 274 information upon LDAP_OPT_API_INFO option access, and 276 MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO 277 option mechanism. The feature version provided MUST match 278 the value LDAP_API_FEATURE_x macro 280 where x is replaced appropriately. 282 As implementations may not provide macros for all features, 283 applications SHOULD use LDAP_OPT_API_INFO to determine which features 284 are provided by a given implementation. 286 8. Changes to the C API specification 288 8.1. New Symbols 290 This extension introduces the following macros: 292 LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES 293 LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES 294 LDAP_API_FEATURE_SESSION_THREAD_SAFE 295 LDAP_API_FEATURE_THREAD_SAFE 296 LDAP_API_FEATURE_OPERATION_THREAD_SAFE LDAP_INVALID_SESSION 297 LDAP_OPT_SESSION_REFCNT 299 This extension introduces these new functions: 301 ldap_destroy() ldap_dup() 303 This extension introduces no new typedefs nor structure names. 305 8.2. Duplicated Session Handles 307 This extension introduces duplicated session handles and requirements 308 for handling duplicated session handles. Semantics of non-duplicated 309 session handles are not affected by this introduction. However, the 310 semantics of calls upon duplicate session handles differs as described 311 in the extension. 313 9. Security Considerations 315 None taken, none given. 317 10. Copyright 319 Copyright 1999, The Internet Society. All Rights Reserved. 321 This document and translations of it may be copied and furnished to 322 others, and derivative works that comment on or otherwise explain it 323 or assist in its implementation may be prepared, copied, published and 324 distributed, in whole or in part, without restriction of any kind, 325 provided that the above copyright notice and this paragraph are 326 included on all such copies and derivative works. However, this 327 document itself may not be modified in any way, such as by removing 328 the copyright notice or references to the Internet Society or other 329 Internet organizations, except as needed for the purpose of 330 developing Internet standards in which case the procedures for 331 copyrights defined in the Internet Standards process must be followed, 332 or as required to translate it into languages other than English. 334 The limited permissions granted above are perpetual and will not be 335 revoked by the Internet Society or its successors or assigns. 337 This document and the information contained herein is provided on an 338 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET 339 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 340 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 341 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 342 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 344 11. Bibliography 346 [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The 347 C LDAP Application Program Interface", INTERNET-DRAFT, + LDAPext discussions, June 1999. 350 [ERRNO] K. Zeilenga, "LDAP C API Error Reporting Extension", 351 INTERNET-DRAFT, , 352 June 1999. 354 [KEYW] S. Bradner, "Key words for use in RFCs to Indicate 355 Requirement Levels", RFC 2119, March 1997. 357 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory 358 Access Protocol (v3)", RFC 2251, December 1997. 360 13. Author's Address 362 Kurt D. Zeilenga 363 OpenLDAP Foundation 364 366 This document expires on 28 March 2000. 368 --------------------------------------------------------------------- 370 Intended Category: Standards Track OpenLDAP Foundation 371 Extends: draft-ietf-ldapext-ldap-c-api-03.txt 372 Expires: 28 March 2000 373 28 September 1999 375 LDAP C API Error Reporting Extension 376 378 1. Status of this Memo 380 This document is an Internet-Draft and is in full conformance with all 381 provisions of Section 10 of RFC2026. 383 This draft document will be submitted to the RFC Editor as a Standards 384 Track document. Distribution of this memo is unlimited. Technical 385 discussion of this document will take place on the IETF LDAP Extension 386 Working Group mailing list . Please send 387 editorial comments directly to the author . 389 Internet-Drafts are working documents of the Internet Engineering Task 390 Force (IETF), its areas, and its working groups. Note that other 391 groups may also distribute working documents as Internet-Drafts. 393 Internet-Drafts are draft documents valid for a maximum of six months 394 and may be updated, replaced, or obsoleted by other documents at any 395 time. It is inappropriate to use Internet-Drafts as reference 396 material or to cite them other than as ``work in progress.'' 398 The list of current Internet-Drafts can be accessed at 399 http://www.ietf.org/ietf/1id-abstracts.txt 401 The list of Internet-Draft Shadow Directories can be accessed at 402 http://www.ietf.org/shadow.html. 404 Copyright 1999, The Internet Society. All Rights Reserved. 406 Please see the Copyright section near the end of this document for 407 more information. 409 2. Abstract 411 This document defines a manatory extension to the LDAP C API to 412 provide error reporting for all API calls. The mechanism is 413 nonintrusive and can, optionally, support concurrent execution 414 environments. 416 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL 417 NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', and ``MAY'' in 418 this document are to be interpreted as described in RFC 2119 [KEYW]. 420 3. Background and Intent of Use 422 The LDAP [LDAP] C API [CAPI] provides an interface which (due to 423 legacy compatibiity issues) does not provide a consistent mechanism 424 for reporting errors. A large number of the calls within the 425 specification have no mechanism to indicate the nature of a failure. 426 The usefulness of a CAPI without a consistent, easy to use, error 427 reporting mechanism is limited. 429 This document defines an mandatory extension to the CAPI. All 430 implementations of the CAPI MUST provide this extension. 432 The extension details additional requirements for error reporting. 433 Implementations MUST fulfill all other CAPI error reporting 434 requirements. 436 4. Error Handling Extension 438 This extension provides a mechanism that applications MAY use to 439 obtain an LDAP error number indicating the nature of the failure 440 associated with the last failed CAPI call. 442 Implementations MUST provide access to an LDAP error number (CAPI, 443 Section 9) resulting from the last failed CAPI call via the symbol 444 ldap_errno. The last failed CAPI call may be within the global 445 context or within the current execution context. 447 The ldap_errno MUST evaluate to a modifiable lvalue that has type 448 'int', the value of which is set to a LDAP error number. It is 449 unspecified whether ldap_errno is a macro or an identifier declared 450 with external linkage. If a macro definition is suppressed in order 451 to access an actual object, or a program defines an identifier with 452 the name ldap_errno, the behavior is undefined. 454 Applications MUST access ldap_errno within the same concurrent 455 execution context, commonly a thread, in which the failure occurred. 456 The value of ldap_errno is LDAP_SUCCESS (0) if no API failure has 457 occurred within the supported context and the user has not assigned a 458 value within the supported context. 460 Implementations SHALL NOT update the ldap_errno value upon successful 461 CAPI call completion. 463 Implementations providing a current execution context specific 464 ldap_errno MUST advertise the feature LDAP_API_CONTEXT_SPECIFIC_ERRNO 465 as described in Section 6. Implementation of 466 LDAP_API_CONTEXT_SPECIFIC_ERRNO is RECOMMENDED. 468 4.1. Reporting Server Errors 470 It is not a CAPI failure for a server to return an error number. 471 Implementations SHALL NOT assign error results returned by servers to 472 ldap_errno. 474 4.2. Implementation Specific Reporting 476 The CAPI specification stated that the caller may obtain an indication 477 of failure of certain calls (see listed below) using implementation 478 specific and/or operating system specific requirements. 479 Implementations are NOT REQUIRED to support any implementation 480 specific and/or operating system mechanism for ANY call detailed by 481 the CAPI specification or its extensions. 483 Affected calls include ldap_init(), ldap_open(), and ber_*(). 485 4.3. Example 487 The following is an example showing how an application may obtain the 488 error information resulting from a failed CAPI calls: 490 int msgid; 491 LDAP *ld = ldap_init("localhost", 389); 493 if(ld == NULL) { 494 printf("ldap_init failed, ldap_errno=%d (%s)\n", 495 ldap_errno, ldap_err2string(ldap_errno)); 497 printf("unable to initialize LDAP session\n"); 498 return -1; 499 } 501 msgid = ldap_simple_bind(ld, NULL, NULL); 503 if(msgid == -1) { 504 int err = ldap_errno; 506 if (err != LDAP_SUCCESS ) { 507 /* API failure */ 508 printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n", 509 err, ldap_err2string(err)); 511 } else { 512 int lderr, rc; 514 printf("ldap_simple_bind failed\n"); 516 rc = ldap_get_option(ld, 517 LDAP_OPT_ERROR_NUMBER, &lderr); 519 if(rc == LDAP_OPT_SUCCESS) { 520 printf(" reason=%d (%s)\n", 521 lderr, ldap_err2string(lderr)); 523 } else { 524 printf("ldap_get_option failed, ldap_errno=%d (%s)\n", 525 ldap_errno, ldap_err2string(ldap_errno)); } 526 } 528 goto unbind; 529 } 531 /* ... */ 533 unbind: if(ldap_unbind(ld) != 0) { 534 printf("ldap_unbind failed, ldap_errno=%d (%s)\n", 535 ldap_errno, ldap_error2str(ldap_errno)); 537 return -1; 538 } 539 return 0; 541 5. Advertising Features 543 This document REQUIRES that supported features with the name in the 544 form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as 545 follows: 547 SHOULD provide the macro LDAP_API_FEATURE_x with the value 548 of 1000 + revision number of this draft (i.e.: 1000+0 for 549 this 0 revision of the draft). 551 MUST provide the CAPI extension "x" when returning API 552 information upon LDAP_OPT_API_INFO option access, and 553 MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO 554 option mechanism. The feature version provided MUST match 555 the value LDAP_API_FEATURE_x macro 557 where x is replaced appropriately. 559 As implementations may not provide macros for all features, 560 applications SHOULD use LDAP_OPT_API_INFO to determine which features 561 are provided by a given implementation. 563 6. Changes to the LDAP C API 565 This section provides a summary of changes to the CAPI specification. 567 6.1. LDAP_API_VERSION 569 LDAP_API_VERSION should be set to the RFC number of this extension if 570 and when it is published as a Standards Track RFC. (see purpose of 571 this draft above). 573 Until such time as this document is published as an RFC, 574 implementations should use the value specified by CAPI plus 100 + 10 * 575 the number of this draft. 577 For the third draft of CAPI and this 0 revision of draft, the value of 578 2103 ((2000+3) + (100+10*0)) should be used. 580 6.2. New Symbols 582 This extension introduces two new symbols: 583 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO ldap_errno 585 LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro. ldap_errno MAY be 586 a MACRO. 588 This extension indroductes no new functions, typedefs, or structure 589 names. 591 6.3. Implementation/System Specific Error Handling 593 This extensions removes any requirements that implementations to use 594 implementation and/or operating system specific error reporting 595 mechanisms. 597 7. Security Considerations 599 None taken, none given. 601 8. Copyright 603 Copyright 1999, The Internet Society. All Rights Reserved. 605 This document and translations of it may be copied and furnished to 606 others, and derivative works that comment on or otherwise explain it 607 or assist in its implementation may be prepared, copied, published and 608 distributed, in whole or in part, without restriction of any kind, 609 provided that the above copyright notice and this paragraph are 610 included on all such copies and derivative works. However, this 611 document itself may not be modified in any way, such as by removing 612 the copyright notice or references to the Internet Society or other 613 Internet organizations, except as needed for the purpose of 614 developing Internet standards in which case the procedures for 615 copyrights defined in the Internet Standards process must be followed, 616 or as required to translate it into languages other than English. 618 The limited permissions granted above are perpetual and will not be 619 revoked by the Internet Society or its successors or assigns. 621 This document and the information contained herein is provided on an 622 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET 623 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 624 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 625 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 626 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 628 9. Bibliography 630 [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, 631 "The C LDAP Application Program Interface", INTERNET-DRAFT, 632 + LDAPext discussions, 633 June 1999. 635 [KEYW] S. Bradner, "Key words for use in RFCs to Indicate 636 Requirement Levels", RFC 2119, March 1997. 638 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory 639 Access Protocol (v3)", RFC 2251, December 1997. 641 10. Author's Address 643 Kurt D. Zeilenga 644 OpenLDAP Foundation 645 647 This document expires on 28 March 2000.