git.sur5r.net Git - openldap/blob - doc/drafts/draft-zeilenga-ldap-c-api-concurrency-xx.txt

   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
   6
   7                     LDAP C API Concurrency Extensions
   8               <draft-zeilenga-ldap-c-api-concurrency-00.txt>
   9
  10 1.   Status of this Memo
  11
  12   This document is an Internet-Draft and is in full conformance with all
  13   provisions of Section 10 of RFC2026.
  14
  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>.
  20
  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.
  24
  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."
  29
  30   The list of current Internet-Drafts can be accessed at
  31   http://www.ietf.org/ietf/1id-abstracts.txt
  32
  33   The list of Internet-Draft Shadow Directories can be accessed at
  34   http://www.ietf.org/shadow.html.
  35
  36   Copyright 1999, The Internet Society.  All Rights Reserved.
  37
  38   Please see the Copyright section near the end of this document for
  39   more information.
  40
  41 2.   Abstract
  42
  43   This document defines extensions to the LDAP C API to support use in
  44   concurrent execution environments.  The document describes and defines
  45
  46 Zeilenga                                                        [Page 1]
  47
  48 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
  49
  50   requirements for multiple concurrency levels: thread safe, session
  51   thread safe, and operation thread safe.
  52
  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].
  56
  57 3.   Introduction
  58
  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.
  65
  66   The remainder of this section describes three levels of concurrent
  67   execution: thread safe, session thread safe, operation thread safe
  68   APIs.
  69
  70 3.1. Thread Safe
  71
  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
  77   implementations.
  78
  79 3.2. Session Thread Safe
  80
  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."
  84
  85 3.3. Operation Thread Safe
  86
  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".
  90
  91 4.   Basic Thread Safe Feature
  92
  93 Zeilenga                                                        [Page 2]
  94
  95 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
  96
  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
 101   implementations.
 102
 103   Implementations of this feature MUST implement the LDAP error handling
 104   extension [ERRNO].
 105
 106   Implementations of this feature MUST allow non-CAPI calls to proceed
 107   asynchronously.
 108
 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)
 113   errno.
 114
 115 5.   Session Thread Safe Feature
 116
 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
 121   RECOMMENDED.
 122
 123 5.1. Prerequisite Features
 124
 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.
 128
 129 5.2. Atomic Session Handles
 130
 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.
 135
 136 5.3. Concurrency Requirements
 137
 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
 141
 142 Zeilenga                                                        [Page 3]
 143
 144 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 145
 146   MUST NOT assume that operations upon a session are atomic.
 147
 148   Implementations providing this feature MUST allow CAPI calls acting
 149   upon different LDAP sessions to safely proceed asynchronously.
 150
 151   Implementations providing this feature MUST allow CAPI calls not
 152   acting upon an LDAP session to safely proceed asynchronously.
 153
 154 6.   Operation Thread Safe Feature
 155
 156   This section details requirements for the operation thread safe CAPI
 157   feature based upon a duplicate session handles mechanism.
 158
 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.
 162
 163 6.1. Prerequisite Features
 164
 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.
 169
 170 6.2. Duplicated Session Handles
 171
 172   Implementations of this feature MUST support duplicated session
 173   handles.
 174
 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.
 183
 184   CAPI calls made on a handle are atomic.  Calls made on sibling (or
 185   other) handles MAY proceed asynchronously.
 186
 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.
 190
 191 Zeilenga                                                        [Page 4]
 192
 193 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 194
 195 6.2.1.    Creating and Destroying duplicated sessions
 196
 197   Implementations of this feature are required to provide two new
 198   routines:      LDAP *ldap_dup( ld );      int ldap_destroy( ld );
 199
 200   Parameters are:      ld      The session handle
 201
 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.
 207
 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.
 218
 219 6.2.2.    ldap_unbind and siblings
 220
 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.
 227
 228 6.2.3.    ldap_result()
 229
 230   Message queues are shared between siblings.  Results of operations on
 231   a duplicated session handles are accessible to all sibling session
 232   handles.
 233
 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
 238   complete.
 239
 240 Zeilenga                                                        [Page 5]
 241
 242 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 243
 244 6.2.4.    Session Options
 245
 246   The following CAPI options access values shared between siblings:
 247
 248        LDAP_OPT_API_INFO      LDAP_OPT_DESC      LDAP_OPT_REFERRALS
 249        LDAP_OPT_PROTOCOL_VERSION      LDAP_OPT_API_FEATURE_INFO
 250        LDAP_OPT_HOST_NAME
 251
 252   The following CAPI options access values specific to a sibling:
 253
 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
 258
 259 6.2.4.1.  LDAP_OPT_SESSION_REFCNT
 260
 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:
 266
 267       int refcount(LDAP *ld) {
 268
 269       #ifdef LDAP_OPT_SESSION_REFCNT
 270
 271         if(ld != NULL) {
 272           int refcnt, rc;
 273           rc = ldap_get_option(ld,
 274               LDAP_OPT_SESSION_REFCNT, &refcnt);
 275
 276           if(rc == LDAP_OPT_SUCCESS) {
 277             return refcnt;
 278           }
 279         }
 280
 281       #endif
 282
 283         return -1;
 284       }
 285
 286 7.   Advertising Features
 287
 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
 290
 291 Zeilenga                                                        [Page 6]
 292
 293 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 294
 295   follows:
 296
 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).
 300
 301        MUST provide the CAPI extension "x" when returning API
 302        information upon LDAP_OPT_API_INFO option access, and
 303
 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
 307
 308   where x is replaced appropriately.
 309
 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.
 313
 314 8.   Changes to the C API specification
 315
 316 8.1. New Symbols
 317
 318   This extension introduces the following macros:
 319
 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
 326
 327   This extension introduces these new functions:
 328
 329        ldap_destroy()      ldap_dup()
 330
 331   This extension introduces no new typedefs nor structure names.
 332
 333 8.2. Duplicated Session Handles
 334
 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
 339   in the extension.
 340
 341 Zeilenga                                                        [Page 7]
 342
 343 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 344
 345 9.   Security Considerations
 346
 347   None taken, none given.
 348
 349 10.  Copyright
 350
 351   Copyright 1999, The Internet Society.  All Rights Reserved.
 352
 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.
 365
 366   The limited permissions granted above are perpetual and will not be
 367   revoked by the Internet Society or its successors or assigns.
 368
 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.
 375
 376 11.  Bibliography
 377
 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.
 381
 382   [ERRNO] K. Zeilenga, "LDAP C API Error Reporting Extension",
 383        INTERNET-DRAFT, <draft-zeilenga-ldap-c-api-errno-00.txt>,
 384        June 1999.
 385
 386   [KEYW]  S. Bradner, "Key words for use in RFCs to Indicate
 387        Requirement Levels", RFC 2119, March 1997.
 388
 389 Zeilenga                                                        [Page 8]
 390
 391 INTERNET-DRAFT      LDAP C API Concurrency Extensions  28 September 1999
 392
 393   [LDAP]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory
 394        Access Protocol (v3)", RFC 2251, December 1997.
 395
 396 13.  Author's Address
 397
 398   Kurt D. Zeilenga
 399   OpenLDAP Foundation
 400   <Kurt@OpenLDAP.org>
 401
 402   This document expires on 28 March 2000.
 403
 404 Zeilenga                                                        [Page 9]
 405
 406     ---------------------------------------------------------------------
 407
 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
 412                                                      28 September 1999
 413
 414                    LDAP C API Error Reporting Extension
 415                  <draft-zeilenga-ldap-c-api-errno-00.txt>
 416
 417 1.   Status of this Memo
 418
 419   This document is an Internet-Draft and is in full conformance with all
 420   provisions of Section 10 of RFC2026.
 421
 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>.
 427
 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.
 431
 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.''
 436
 437   The list of current Internet-Drafts can be accessed at
 438   http://www.ietf.org/ietf/1id-abstracts.txt
 439
 440   The list of Internet-Draft Shadow Directories can be accessed at
 441   http://www.ietf.org/shadow.html.
 442
 443   Copyright 1999, The Internet Society.  All Rights Reserved.
 444
 445   Please see the Copyright section near the end of this document for
 446   more information.
 447
 448 2.   Abstract
 449
 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
 453   environments.
 454
 455 Zeilenga                                                        [Page 1]
 456
 457 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 458
 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].
 462
 463 3.   Background and Intent of Use
 464
 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.
 471
 472   This document defines an mandatory extension to the CAPI.  All
 473   implementations of the CAPI MUST provide this extension.
 474
 475   The extension details additional requirements for error reporting.
 476   Implementations MUST fulfill all other CAPI error reporting
 477   requirements.
 478
 479 4.   Error Handling Extension
 480
 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.
 484
 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.
 489
 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.
 496
 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.
 502
 503 Zeilenga                                                        [Page 2]
 504
 505 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 506
 507   Implementations SHALL NOT update the ldap_errno value upon successful
 508   CAPI call completion.
 509
 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.
 514
 515 4.1. Reporting Server Errors
 516
 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
 519   ldap_errno.
 520
 521 4.2. Implementation Specific Reporting
 522
 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.
 529
 530   Affected calls include ldap_init(), ldap_open(), and ber_*().
 531
 532 4.3. Example
 533
 534   The following is an example showing how an application may obtain the
 535   error information resulting from a failed CAPI calls:
 536
 537     int msgid;
 538     LDAP *ld = ldap_init("localhost", 389);
 539
 540     if(ld == NULL) {
 541       printf("ldap_init failed, ldap_errno=%d (%s)\n",
 542         ldap_errno, ldap_err2string(ldap_errno));
 543
 544       printf("unable to initialize LDAP session\n");
 545       return -1;
 546     }
 547
 548     msgid = ldap_simple_bind(ld, NULL, NULL);
 549
 550     if(msgid == -1) {
 551       int err = ldap_errno;
 552
 553       if (err != LDAP_SUCCESS ) {
 554
 555 Zeilenga                                                        [Page 3]
 556
 557 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 558
 559         /* API failure */
 560         printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n",
 561           err, ldap_err2string(err));
 562
 563       } else {
 564         int lderr, rc;
 565
 566         printf("ldap_simple_bind failed\n");
 567
 568         rc = ldap_get_option(ld,
 569           LDAP_OPT_ERROR_NUMBER, &lderr);
 570
 571         if(rc == LDAP_OPT_SUCCESS) {
 572           printf("  reason=%d (%s)\n",
 573             lderr, ldap_err2string(lderr));
 574
 575         } else {
 576           printf("ldap_get_option failed, ldap_errno=%d (%s)\n",
 577             ldap_errno, ldap_err2string(ldap_errno));        }
 578       }
 579
 580       goto unbind;
 581     }
 582
 583     /* ... */
 584
 585     unbind: if(ldap_unbind(ld) != 0) {
 586       printf("ldap_unbind failed, ldap_errno=%d (%s)\n",
 587         ldap_errno, ldap_error2str(ldap_errno));
 588
 589       return -1;
 590     }
 591     return 0;
 592
 593 5.   Advertising Features
 594
 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
 597   follows:
 598
 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).
 602
 603        MUST provide the CAPI extension "x" when returning API
 604        information upon LDAP_OPT_API_INFO option access, and
 605
 606 Zeilenga                                                        [Page 4]
 607
 608 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 609
 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
 613
 614   where x is replaced appropriately.
 615
 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.
 619
 620 6.   Changes to the LDAP C API
 621
 622   This section provides a summary of changes to the CAPI specification.
 623
 624 6.1. LDAP_API_VERSION
 625
 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
 628   this draft above).
 629
 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.
 633
 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.
 636
 637 6.2. New Symbols
 638
 639   This extension introduces two new symbols:
 640        LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO      ldap_errno
 641
 642   LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro.  ldap_errno MAY be
 643   a MACRO.
 644
 645   This extension indroductes no new functions, typedefs, or structure
 646   names.
 647
 648 6.3. Implementation/System Specific Error Handling
 649
 650   This extensions removes any requirements that implementations to use
 651   implementation and/or operating system specific error reporting
 652   mechanisms.
 653
 654 Zeilenga                                                        [Page 5]
 655
 656 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 657
 658 7.   Security Considerations
 659
 660   None taken, none given.
 661
 662 8.   Copyright
 663
 664   Copyright 1999, The Internet Society.  All Rights Reserved.
 665
 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.
 678
 679   The limited permissions granted above are perpetual and will not be
 680   revoked by the Internet Society or its successors or assigns.
 681
 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.
 688
 689 9.   Bibliography
 690
 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,
 694        June 1999.
 695
 696   [KEYW]  S. Bradner, "Key words for use in RFCs to Indicate
 697           Requirement Levels", RFC 2119, March 1997.
 698
 699   [LDAP]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory
 700           Access Protocol (v3)", RFC 2251, December 1997.
 701
 702 Zeilenga                                                        [Page 6]
 703
 704 INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999
 705
 706 10.  Author's Address
 707
 708   Kurt D. Zeilenga
 709   OpenLDAP Foundation
 710   <Kurt@OpenLDAP.org>
 711
 712   This document expires on 28 March 2000.
 713
 714 Zeilenga                                                        [Page 7]