One document matched: draft-zeilenga-ldap-c-api-errno-00.txt

INTERNET-DRAFT                                        Kurt D. Zeilenga
Intended Category: Standards Track                 OpenLDAP Foundation
Extends: draft-ietf-ldapext-ldap-c-api-03.txt
Expires: 28 March 2000
                                                     28 September 1999

                   LDAP C API Error Reporting Extension
                 <draft-zeilenga-ldap-c-api-errno-00.txt>

1.   Status of this Memo 

  This document is an Internet-Draft and is in full conformance with all
  provisions of Section 10 of RFC2026.

  This draft document will be submitted to the RFC Editor as a Standards
  Track document. Distribution of this memo is unlimited.  Technical
  discussion of this document will take place on the IETF LDAP Extension
  Working Group mailing list <ietf-ldapext@netscape.com>.  Please send
  editorial comments directly to the author <Kurt@OpenLDAP.org>.

  Internet-Drafts are working documents of the Internet Engineering Task
  Force (IETF), its areas, and its working groups.  Note that other
  groups may also distribute working documents as Internet-Drafts.

  Internet-Drafts are draft documents valid for a maximum of six months
  and may be updated, replaced, or obsoleted by other documents at any
  time.  It is inappropriate to use Internet-Drafts as reference
  material or to cite them other than as ``work in progress.''

  The list of current Internet-Drafts can be accessed at
  http://www.ietf.org/ietf/1id-abstracts.txt

  The list of Internet-Draft Shadow Directories can be accessed at
  http://www.ietf.org/shadow.html.

  Copyright 1999, The Internet Society.  All Rights Reserved.

  Please see the Copyright section near the end of this document for
  more information.

2.   Abstract

  This document defines a manatory extension to the LDAP C API to
  provide error reporting for all API calls.  The mechanism is
  nonintrusive and can, optionally, support concurrent execution
  environments.

Zeilenga                                                        [Page 1]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

  The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL
  NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'',  and ``MAY'' in
  this document are to be interpreted as described in RFC 2119 [KEYW].

3.   Background and Intent of Use

  The LDAP [LDAP] C API [CAPI] provides an interface which (due to
  legacy compatibiity issues) does not provide a consistent mechanism
  for reporting errors.  A large number of the calls within the
  specification have no mechanism to indicate the nature of a failure.
  The usefulness of a CAPI without a consistent, easy to use, error
  reporting mechanism is limited.

  This document defines an mandatory extension to the CAPI.  All
  implementations of the CAPI MUST provide this extension.

  The extension details additional requirements for error reporting.
  Implementations MUST fulfill all other CAPI error reporting
  requirements.

4.   Error Handling Extension

  This extension provides a mechanism that applications MAY use to
  obtain an LDAP error number indicating the nature of the failure
  associated with the last failed CAPI call.

  Implementations MUST provide access to an LDAP error number (CAPI,
  Section 9) resulting from the last failed CAPI call via the symbol
  ldap_errno.  The last failed CAPI call may be within the global
  context or within the current execution context.

  The ldap_errno MUST evaluate to a modifiable lvalue that has type
  'int', the value of which is set to a LDAP error number.  It is
  unspecified whether ldap_errno is a macro or an identifier declared
  with external linkage.  If a macro definition is suppressed in order
  to access an actual object, or a program defines an identifier with
  the name ldap_errno, the behavior is undefined.

  Applications MUST access ldap_errno within the same concurrent
  execution context, commonly a thread, in which the failure occurred.
  The value of ldap_errno is LDAP_SUCCESS (0) if no API failure has
  occurred within the supported context and the user has not assigned a
  value within the supported context.

Zeilenga                                                        [Page 2]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

  Implementations SHALL NOT update the ldap_errno value upon successful
  CAPI call completion.

  Implementations providing a current execution context specific
  ldap_errno MUST advertise the feature LDAP_API_CONTEXT_SPECIFIC_ERRNO
  as described in Section 6.  Implementation of
  LDAP_API_CONTEXT_SPECIFIC_ERRNO is RECOMMENDED.

4.1. Reporting Server Errors

  It is not a CAPI failure for a server to return an error number.
  Implementations SHALL NOT assign error results returned by servers to
  ldap_errno.

4.2. Implementation Specific Reporting

  The CAPI specification stated that the caller may obtain an indication
  of failure of certain calls (see listed below) using implementation
  specific and/or operating system specific requirements.
  Implementations are NOT REQUIRED to support any implementation
  specific and/or operating system mechanism for ANY call detailed by
  the CAPI specification or its extensions.

  Affected calls include ldap_init(), ldap_open(), and ber_*().

4.3. Example

  The following is an example showing how an application may obtain the
  error information resulting from a failed CAPI calls:

    int msgid;
    LDAP *ld = ldap_init("localhost", 389);

    if(ld == NULL) {
      printf("ldap_init failed, ldap_errno=%d (%s)\n",
        ldap_errno, ldap_err2string(ldap_errno));

      printf("unable to initialize LDAP session\n");
      return -1;
    }

    msgid = ldap_simple_bind(ld, NULL, NULL);

    if(msgid == -1) {
      int err = ldap_errno;

      if (err != LDAP_SUCCESS ) {

Zeilenga                                                        [Page 3]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

        /* API failure */
        printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n",
          err, ldap_err2string(err));

      } else {
        int lderr, rc;

        printf("ldap_simple_bind failed\n");

        rc = ldap_get_option(ld,
          LDAP_OPT_ERROR_NUMBER, &lderr);

        if(rc == LDAP_OPT_SUCCESS) {
          printf("  reason=%d (%s)\n",
            lderr, ldap_err2string(lderr));

        } else {
          printf("ldap_get_option failed, ldap_errno=%d (%s)\n",
            ldap_errno, ldap_err2string(ldap_errno));        }
      }

      goto unbind;
    }

    /* ... */

    unbind: if(ldap_unbind(ld) != 0) {
      printf("ldap_unbind failed, ldap_errno=%d (%s)\n",
        ldap_errno, ldap_error2str(ldap_errno));

      return -1;
    }
    return 0;

5.   Advertising Features

  This document REQUIRES that supported features with the name in the
  form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as
  follows:

       SHOULD provide the macro LDAP_API_FEATURE_x with the value
       of 1000 + revision number of this draft (i.e.: 1000+0 for
       this 0 revision of the draft).

       MUST provide the CAPI extension "x" when returning API
       information upon LDAP_OPT_API_INFO option access, and

Zeilenga                                                        [Page 4]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

       MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO
       option mechanism.  The feature version provided MUST      match
  the value LDAP_API_FEATURE_x macro

  where x is replaced appropriately.

  As implementations may not provide macros for all features,
  applications SHOULD use LDAP_OPT_API_INFO to determine which features
  are provided by a given implementation.

6.   Changes to the LDAP C API

  This section provides a summary of changes to the CAPI specification.

6.1. LDAP_API_VERSION

  LDAP_API_VERSION should be set to the RFC number of this extension if
  and when it is published as a Standards Track RFC.  (see purpose of
  this draft above).

  Until such time as this document is published as an RFC,
  implementations should use the value specified by CAPI plus 100 + 10 *
  the number of this draft.

  For the third draft of CAPI and this 0 revision of draft, the value of
  2103 ((2000+3) + (100+10*0)) should be used.

6.2. New Symbols

  This extension introduces two new symbols:
       LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO      ldap_errno

  LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro.  ldap_errno MAY be
  a MACRO.

  This extension indroductes no new functions, typedefs, or structure
  names.

6.3. Implementation/System Specific Error Handling

  This extensions removes any requirements that implementations to use
  implementation and/or operating system specific error reporting
  mechanisms.

Zeilenga                                                        [Page 5]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

7.   Security Considerations

  None taken, none given.

8.   Copyright

  Copyright 1999, The Internet Society.  All Rights Reserved.

  This document and translations of it may be copied and furnished to
  others, and derivative works that comment on or otherwise explain it
  or assist in its implementation may be prepared, copied, published and
  distributed, in whole or in part, without restriction of any kind,
  provided that the above copyright notice and this paragraph are
  included on all such copies and derivative works.  However, this
  document itself may not be modified in any way, such as by removing
  the copyright notice or references to the Internet Society or other
  Internet organizations, except as needed for the  purpose of
  developing Internet standards in which case the procedures for
  copyrights defined in the Internet Standards process must be followed,
  or as required to translate it into languages other than English.

  The limited permissions granted above are perpetual and will not be
  revoked by the Internet Society or its successors or assigns.

  This document and the information contained herein is provided on an
  "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
  ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
  INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
  INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
  WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

9.   Bibliography

  [CAPI]  M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha,
          "The C LDAP Application Program Interface", INTERNET-DRAFT,
          <draft-ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions,
       June 1999.

  [KEYW]  S. Bradner, "Key words for use in RFCs to Indicate
          Requirement Levels", RFC 2119, March 1997.

  [LDAP]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory
          Access Protocol (v3)", RFC 2251, December 1997.

Zeilenga                                                        [Page 6]

INTERNET-DRAFT    LDAP C API Error Reporting Extension 28 September 1999

10.  Author's Address

  Kurt D. Zeilenga
  OpenLDAP Foundation
  <Kurt@OpenLDAP.org>

  This document expires on 28 March 2000.

Zeilenga                                                        [Page 7]