diff --git a/doc/draft-ietf-asid-ldap-c-api-00.txt b/doc/draft-ietf-asid-ldap-c-api-00.txt
deleted file mode 100755
index 5f2e856..0000000
--- a/doc/draft-ietf-asid-ldap-c-api-00.txt
+++ /dev/null
@@ -1,3030 +0,0 @@
-
-
-
-
-
-
-Network Working Group                                           T. Howes
-INTERNET-DRAFT                             Netscape Communications Corp.
-Intended Category: Standards Track                              M. Smith
-Obsoletes: RFC 1823                        Netscape Communications Corp.
-Expires: January 1998                                          A. Herron
-                                                         Microsoft Corp.
-                                                               C. Weider
-                                                         Microsoft Corp.
-                                                                 M. Wahl
-                                                    Critical Angle, Inc.
-
-                                                            29 July 1997
-
-
-                The C LDAP Application Program Interface
-                  <draft-ietf-asid-ldap-c-api-00.txt>
-
-
-
-1.  Status of this Memo
-
-This draft document will be submitted to the RFC Editor as a Standards
-Track document. Distribution of this memo is unlimited. Please send com-
-ments to the authors.
-
-This document is an Internet-Draft.  Internet-Drafts are working docu-
-ments 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.''
-
-To learn the current status of any Internet-Draft, please check the
-``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
-Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
-ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
-
-2.  Introduction
-
-This document defines a C language application program interface to the
-lightweight directory access protocol (LDAP). This document replaces the
-previous definition of this API, defined in RFC 1823, updating it to
-include support for features found in version 3 of the LDAP protocol.
-New extended operation functions were added to support LDAPv3 features
-such as controls.  In addition, other LDAP API changes were made to
-
-
-
-Expires: January 1998                                           [Page 1]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-support information hiding and thread safety.
-
-The C LDAP API is designed to be powerful, yet simple to use. It defines
-compatible synchronous and asynchronous interfaces to LDAP to suit a
-wide variety of applications. This document gives a brief overview of
-the LDAP model, then an overview of how the API is used by an applica-
-tion program to obtain LDAP information.  The API calls are described in
-detail, followed by an appendix that provides some example code demon-
-strating the use of the API. This document provides information to the
-Internet community. It does not specify any standard.
-
-3.  Overview of the LDAP Model
-
-LDAP is the lightweight directory access protocol, described in [2] and
-[6]. It can provide a lightweight frontend to the X.500 directory [1],
-or a stand-alone service. In either mode, LDAP is based on a client-
-server model in which a client makes a TCP connection to an LDAP server,
-over which it sends requests and receives responses.
-
-The LDAP information model is based on the entry, which contains infor-
-mation about some object (e.g., a person).  Entries are composed of
-attributes, which have a type and one or more values. Each attribute has
-a syntax that determines what kinds of values are allowed in the attri-
-bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
-values behave during directory operations (e.g., is case significant
-during comparisons).
-
-Entries may be organized in a tree structure, usually based on politi-
-cal, geographical, and organizational boundaries. Each entry is uniquely
-named relative to its sibling entries by its relative distinguished name
-(RDN) consisting of one or more distinguished attribute values from the
-entry.  At most one value from each attribute may be used in the RDN.
-For example, the entry for the person Babs Jensen might be named with
-the "Barbara Jensen" value from the commonName attribute.
-
-A globally unique name for an entry, called a distinguished name or DN,
-is constructed by concatenating the sequence of RDNs from the entry up
-to the root of the tree. For example, if Babs worked for the University
-of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
-o=University of Michigan, c=US". The DN format used by LDAP is defined
-in [4].
-
-Operations are provided to authenticate, search for and retrieve infor-
-mation, modify information, and add and delete entries from the tree.
-The next sections give an overview of how the API is used and detailed
-descriptions of the LDAP API calls that implement all of these func-
-tions.
-
-
-
-
-Expires: January 1998                                           [Page 2]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-4.  Overview of LDAP API Use
-
-An application generally uses the C LDAP API in four simple steps.
-
--    Initialize an LDAP session with a default LDAP server. The
-     ldap_init() function returns a handle to the session, allowing mul-
-     tiple connections to be open at once.
-
--    Authenticate to the LDAP server. The ldap_bind() function and
-     friends support a variety of authentication methods.
-
--    Perform some LDAP operations and obtain some results. ldap_search()
-     and friends return results which can be parsed by
-     ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.
-
--    Close the session. The ldap_unbind() function closes the connec-
-     tion.
-
-Operations can be performed either synchronously or asynchronously.  The
-names of the synchronous functions end in _s. For example, a synchronous
-search can be completed by calling ldap_search_s(). An asynchronous
-search can be initiated by calling ldap_search(). All synchronous rou-
-tines return an indication of the outcome of the operation (e.g, the
-constant LDAP_SUCCESS or some other error code).  The asynchronous rou-
-tines return the message id of the operation initiated. This id can be
-used in subsequent calls to ldap_result() to obtain the result(s) of the
-operation. An asynchronous operation can be abandoned by calling
-ldap_abandon().
-
-Results and errors are returned in an opaque structure called LDAPMes-
-sage.  Routines are provided to parse this structure, step through
-entries and attributes returned, etc. Routines are also provided to
-interpret errors. Later sections of this document describe these rou-
-tines in more detail.
-
-LDAP version 3 servers may return referrals to other servers.  By
-default, implementations of this API will attempt to follow referrals
-automatically for the application.  This behavior can be disabled glo-
-bally (using the ldap_set_option() call) or on a per-request basis
-through the use of a client control.
-
-As in the LDAPv3 protocol itself, all DNs and string values that are
-passed into or produced by the C LDAP API are represented as UTF-8[10]
-characters.
-
-For compatibility with existing applications, implementations of this
-API will by default use version 2 of the LDAP protocol.  Applications
-that intend to take advantage of LDAP version 3 features will need to
-
-
-
-Expires: January 1998                                           [Page 3]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
-switch to version 3.
-
-
-5.  Common Data Structures
-
-Some data structures that are common to several LDAP API functions are
-defined here:
-
-           typedef struct ldap LDAP;
-
-           typedef struct ldapmsg LDAPMessage;
-
-           struct berval {
-                   unsigned long   bv_len;
-                   char            *bv_val;
-           };
-
-           struct timeval {
-                   long            tv_sec;
-                   long            tv_usec;
-           };
-
-The LDAP structure is an opaque data type that represents an LDAP ses-
-sion Typically this corresponds to a connection to a single server, but
-it may encompass several server connections in the face of LDAPv3 refer-
-rals.
-
-The LDAPMessage structure is an opaque data type that is used to return
-results and error information.
-
-The berval structure is used to represent arbitrary binary data and its
-fields have the following meanings:
-
-bv_len   Length of data in bytes.
-
-bv_val   A pointer to the data itself.
-
-
-The timeval structure is used to represent an interval of time and its
-fields have the following meanings:
-
-tv_sec   Seconds component of time interval.
-
-tv_usec  Microseconds component of time interval.
-
-
-
-
-
-
-Expires: January 1998                                           [Page 4]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-6.  LDAP Error Codes
-
-Many of the LDAP API routines return LDAP error codes, some of which
-indicate local errors and some of which may be returned by servers.
-Supported error codes are (hexadecimal values are given in parentheses
-after the constant):
-
-           LDAP_SUCCESS (0x00)
-           LDAP_OPERATIONS_ERROR( 0x01)
-           LDAP_PROTOCOL_ERROR (0x02)
-           LDAP_TIMELIMIT_EXCEEDED (0x03)
-           LDAP_SIZELIMIT_EXCEEDED (0x04)
-           LDAP_COMPARE_FALSE (0x05)
-           LDAP_COMPARE_TRUE (0x06)
-           LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
-           LDAP_STRONG_AUTH_REQUIRED (0x08)
-           LDAP_REFERRAL (0x0a)                            -- new in LDAPv3
-           LDAP_ADMINLIMIT_EXCEEDED (0x0b)                 -- new in LDAPv3
-           LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c)      -- new in LDAPv3
-           LDAP_CONFIDENTIALITY_REQUIRED (0x0d)            -- new in LDAPv3
-           LDAP_NO_SUCH_ATTRIBUTE (0x10)
-           LDAP_UNDEFINED_TYPE (0x11)
-           LDAP_INAPPROPRIATE_MATCHING (0x12)
-           LDAP_CONSTRAINT_VIOLATION (0x13)
-           LDAP_TYPE_OR_VALUE_EXISTS (0x14)
-           LDAP_INVALID_SYNTAX (0x15)
-           LDAP_NO_SUCH_OBJECT (0x20)
-           LDAP_ALIAS_PROBLEM (0x21)
-           LDAP_INVALID_DN_SYNTAX (0x22)
-           LDAP_IS_LEAF (0x23)                             -- not used in LDAPv3
-           LDAP_ALIAS_DEREF_PROBLEM (0x24)
-           LDAP_INAPPROPRIATE_AUTH (0x30)
-           LDAP_INVALID_CREDENTIALS (0x31)
-           LDAP_INSUFFICIENT_ACCESS (0x32)
-           LDAP_BUSY (0x33)
-           LDAP_UNAVAILABLE (0x34)
-           LDAP_UNWILLING_TO_PERFORM (0x35)
-           LDAP_LOOP_DETECT (0x36)
-           LDAP_NAMING_VIOLATION (0x40)
-           LDAP_OBJECT_CLASS_VIOLATION (0x41)
-           LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
-           LDAP_NOT_ALLOWED_ON_RDN (0x43)
-           LDAP_ALREADY_EXISTS (0x44)
-           LDAP_NO_OBJECT_CLASS_MODS (0x45)
-           LDAP_RESULTS_TOO_LARGE (0x46)
-           LDAP_AFFECTS_MULTIPLE_DSAS (0x47)               -- new in LDAPv3
-           LDAP_OTHER (0x50)
-           LDAP_SERVER_DOWN (0x51)
-
-
-
-Expires: January 1998                                           [Page 5]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           LDAP_LOCAL_ERROR (0x52)
-           LDAP_ENCODING_ERROR (0x53)
-           LDAP_DECODING_ERROR (0x54)
-           LDAP_TIMEOUT (0x55)
-           LDAP_AUTH_UNKNOWN (0x56)
-           LDAP_FILTER_ERROR (0x57)
-           LDAP_USER_CANCELLED (0x58)
-           LDAP_PARAM_ERROR (0x59)
-           LDAP_NO_MEMORY (0x5a)
-           LDAP_CONNECT_ERROR (0x5b)
-           LDAP_NOT_SUPPORTED (0x5c)
-           LDAP_CONTROL_NOT_FOUND (0x5d)
-           LDAP_NO_RESULTS_RETURNED (0x5e)
-           LDAP_MORE_RESULTS_TO_RETURN (0x5f)
-           LDAP_CLIENT_LOOP (0x60)
-           LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
-
-
-7.  Performing LDAP Operations
-
-This section describes each LDAP operation API call in detail. All func-
-tions take a "session handle," a pointer to an LDAP structure containing
-per-connection information.  Many routines return results in an LDAPMes-
-sage structure. These structures and others are described as needed
-below.
-
-
-7.1.  Initializing an LDAP Session
-
-ldap_init() initializes a session with an LDAP server. The server is not
-actually contacted until an operation is performed that requires it,
-allowing various options to be set after initialization.
-
-        LDAP *ldap_init(
-                char    *hostname,
-                int     portno
-        );
-
-Use of the following routine is deprecated.
-
-        LDAP *ldap_open(
-                char    *hostname,
-                int     portno
-        );
-
-Parameters are:
-
-hostname Contains a space-separated list of hostnames or dotted strings
-
-
-
-Expires: January 1998                                           [Page 6]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-         representing the IP address of hosts running an LDAP server to
-         connect to. Each hostname in the list can include an optional
-         port number which is separated from the host itself with a
-         colon (:) character.  The hosts are tried in the order listed,
-         stopping with the first one to which a successful connection is
-         made. Note that only ldap_open() attempts to make the connec-
-         tion before returning to the caller. ldap_init() does not con-
-         nect to the LDAP server.
-
-portno   Contains the TCP port number to connect to. The default LDAP
-         port of 389 can be obtained by supplying the constant
-         LDAP_PORT.  If a host includes a port number then this parame-
-         ter is ignored.
-
-ldap_init() and ldap_open() both return a "session handle," a pointer to
-an opaque structure that should be passed to subsequent calls pertaining
-to the session. These routines return NULL if the session cannot be ini-
-tialized in which case the operating system error reporting mechanism
-can be checked to see why the call failed.
-
-Note that if you connect to an LDAPv2 server, one of the ldap_bind()
-calls described below must be completed before other operations can be
-performed on the session.  LDAPv3 does not require that a bind operation
-be completed before other operations can be performed.
-
-The calling program can set various attributes of the session by calling
-the routines described in the next section.
-
-
-7.2.  LDAP Session Handle Options
-
-The LDAP session handle returned by ldap_init() is a pointer to an
-opaque data type representing an LDAP session. Formerly, this data type
-was a structure exposed to the caller, and various fields in the struc-
-ture could be set to control aspects of the session, such as size and
-time limits on searches.
-
-In the interest of insulating callers from inevitable changes to this
-structure, these aspects of the session are now accessed through a pair
-of accessor functions, described below.
-
-ldap_get_option() is used to access the current value of various
-session-wide parameters. ldap_set_option() is used to set the value of
-these parameters.
-
-           int ldap_get_option(
-                   LDAP            *ld,
-                   int             option,
-
-
-
-Expires: January 1998                                           [Page 7]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-                   void            *outvalue
-           );
-
-           int ldap_set_option(
-                   LDAP            *ld,
-                   int             option,
-                   void            *invalue
-           );
-
-Parameters are:
-
-ld     The session handle.
-
-option The name of the option being accessed or set. This parameter
-       should be one of the following constants, which have the indi-
-       cated meanings.  After the constant the actual value of the con-
-       stant is listed in hexadecimal in parentheses followed by the
-       type of the corresponding outvalue or invalue parameter.
-
-   LDAP_OPT_DESC (0x01) int *
-          The underlying socket descriptor corresponding to the default
-          LDAP connection.
-
-   LDAP_OPT_DEREF (0x02) int *
-          Controls how aliases are handled during search. It can have
-          one of the following values: LDAP_DEREF_NEVER (0x00),
-          LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
-          LDAP_DEREF_ALWAYS (0x03).  The LDAP_DEREF_SEARCHING value
-          means aliases should be dereferenced during the search but not
-          when locating the base object of the search. The
-          LDAP_DEREF_FINDING value means aliases should be dereferenced
-          when locating the base object but not during the search.
-
-   LDAP_OPT_SIZELIMIT (0x03) int *
-          A limit on the number of entries to return from a search. A
-          value of zero means no limit.
-
-   LDAP_OPT_TIMELIMIT (0x04) int *
-          A limit on the number of seconds to spend on a search. A value
-          of zero means no limit
-
-   LDAP_OPT_REBIND_FN (0x06) function pointer
-          See the discussion of ldap_bind() and friends below.
-
-   LDAP_OPT_REBIND_ARG (0x07) void *
-          See the discussion of ldap_bind() and friends below.
-
-   LDAP_OPT_REFERRALS (0x08) void *
-
-
-
-Expires: January 1998                                           [Page 8]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-          This option controls whether the LDAP library automatically
-          follows referrals returned by LDAP servers or not. It can be
-          set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.
-
-   LDAP_OPT_RESTART (0x09) void *
-          This option controls whether LDAP I/O operations should
-          automatically be restarted if they abort prematurely. It
-          should be set to one of the constants LDAP_OPT_ON or
-          LDAP_OPT_OFF. This option is useful if an LDAP I/O operation
-          may be interrupted prematurely, for example by a timer going
-          off, or other interrrupt.
-
-   LDAP_OPT_PROTOCOL_VERSION (0x11) int *
-          This option indicates the version of the default LDAP server.
-          It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3.
-          If no version is set the default is LDAP_VERSION2.
-
-   LDAP_OPT_SERVER_CONTROLS (0x12) LDAPControl **
-          A default list of LDAP server controls to be sent with each
-          request.  See the Using Controls section below.
-
-   LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl **
-          A default list of client controls that affect the LDAP ses-
-          sion.  See the Using Controls section below.
-
-   LDAP_OPT_HOST_NAME (0x30) char **
-          The host name of the default LDAP server.
-
-   LDAP_OPT_ERROR_NUMBER (0x31) int *
-          The code of the most recent LDAP error that occurred for this
-          session.
-
-   LDAP_OPT_ERROR_STRING (0x32) char **
-          The message returned with the most recent LDAP error that
-          occurred for this session.
-
-
-outvalue The address of a place to put the value of the option. The
-         actual type of this parameter depends on the setting of the
-         option parameter.
-
-invalue  A pointer to the value the option is to be given. The actual
-         type of this parameter depends on the setting of the option
-         parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be
-         given for options that have on or off settings.
-
-
-
-
-
-
-Expires: January 1998                                           [Page 9]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-7.3.  Working with controls
-
-LDAPv3 operations can be extended through the use of controls.  Controls
-may be sent to a server or returned to the client with any LDAP message.
-These controls are referred to as server controls.
-
-The LDAP API also supports a client-side extension mechanism through the
-use of client controls. These controls affect the behavior of the LDAP
-API only and are never sent to a server.  A common data structure is
-used to represent both types of controls:
-
-           typedef struct ldapcontrol {
-                   char            *ldctl_oid;
-                   struct berval   ldctl_value;
-                   char            ldctl_iscritical;
-           } LDAPControl, *PLDAPControl;
-
-The fields in the ldapcontrol structure have the following meanings:
-
-ldctl_oid        The control type, represented as a string.
-
-ldctl_value      The data associated with the control (if any).
-
-ldctl_iscritical Indicates whether the control is critical of not. If
-                 this field is non-zero, the operation will only be car-
-                 ried out if the control is recognized by the server
-                 and/or client.
-
-Some LDAP API calls allocate an ldapcontrol structure or a NULL-
-terminated array of ldapcontrol structures.  The following routines can
-be used to dispose of a single control or an array of controls:
-
-           void ldap_control_free( LDAPControl *ctrl );
-           void ldap_controls_free( LDAPControl **ctrls );
-
-A set of controls that affect the entire session can be set using the
-ldap_set_option() function (see above).  A list of controls can also be
-passed directly to some LDAP API calls such as ldap_search_ext(), in
-which case any controls set for the session through the use of
-ldap_set_option() are ignored. Control lists are represented as a NULL-
-terminated array of pointers to ldapcontrol structures.
-
-Server controls are defined by LDAPv3 protocol extension documents; for
-example, a control has been proposed to support server-side sorting of
-search results [7].
-
-No client controls are defined by this document but they may be defined
-in future revisions or in any document that extends this API.
-
-
-
-Expires: January 1998                                          [Page 10]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-7.4.  Authenticating to the directory
-
-The following functions are used to authenticate an LDAP client to an
-LDAP directory server.
-
-The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
-general and extensible authentication over LDAP through the use of the
-Simple Authentication Security Layer [8].  The routines both take the dn
-to bind as, the method to use, as a dotted-string representation of an
-OID identifying the method, and a struct berval holding the credentials.
-The special constant value LDAP_SASL_SIMPLE ("") can be passed to
-request simple authentication, or the simplified routines
-ldap_simple_bind() or ldap_simple_bind_s() can be used.
-
-           int ldap_sasl_bind(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *mechanism,
-                   struct berval   *cred,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-           int ldap_sasl_bind_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *mechanism,
-                   struct berval   *cred,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   struct berval   **servercredp
-           );
-
-           int ldap_simple_bind(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *passwd
-           );
-
-           int ldap_simple_bind_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *passwd
-           );
-
-   The use of the following routines is deprecated:
-
-
-
-
-Expires: January 1998                                          [Page 11]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
-
-           int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
-
-           int ldap_kerberos_bind( LDAP *ld, char *dn );
-
-           int ldap_kerberos_bind_s( LDAP *ld, char *dn );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry to bind as.
-
-mechanism    Either LDAP_AUTH_SIMPLE_OID to get simple authentication,
-             or a dotted text string representing an OID identifying the
-             SASL method.
-
-cred         The credentials with which to authenticate. Arbitrary
-             credentials can be passed using this parameter. The format
-             and content of the credentials depends on the setting of
-             the mechanism parameter.
-
-passwd       For ldap_simple_bind(), the password to compare to the
-             entry's userPassword attribute.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_sasl_bind() call succeeds.
-
-servercredp  This result parameter will be set to the credentials
-             returned by the server.  This should be freed by calling
-             ldap_If no credentials are returned it will be set to NULL.
-
-Additional parameters for the deprecated routines are not described.
-Interested readers are referred to RFC 1823.
-
-The ldap_sasl_bind() function initiates an asynchronous bind operation
-and returns the constant LDAP_SUCCESS if the request was successfully
-sent, or another LDAP error code if not.  See the section below on error
-handling for more information about possible errors and how to interpret
-them.  If successful, ldap_sasl_bind() places the message id of the
-request in *msgidp. A subsequent call to ldap_result(), described below,
-can be used to obtain the result of the bind.
-
-
-
-
-Expires: January 1998                                          [Page 12]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-The ldap_simple_bind() function initiates a simple asynchronous bind
-operation and returns the message id of the operation initiated.  A sub-
-sequent call to ldap_result(), described below, can be used to obtain
-the result of the bind. In case of error, ldap_simple_bind() will return
--1, setting the session error parameters in the LDAP structure appropri-
-ately.
-
-The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
-both return the result of the operation, either the constant
-LDAP_SUCCESS if the operation was successful, or another LDAP error code
-if it was not. See the section below on error handling for more informa-
-tion about possible errors and how to interpret them.
-
-Note that if an LDAPv2 server is contacted, no other operations over the
-connection should be attempted before a bind call has successfully com-
-pleted.
-
-Subsequent bind calls can be used to re-authenticate over the same con-
-nection, and multistep SASL sequences can be accomplished through a
-sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
-
-
-7.5.  Closing the session
-
-The following functions are used to unbind from the directory, close the
-connection, and dispose of the session handle.
-
-           int ldap_unbind( LDAP *ld );
-
-           int ldap_unbind_s( LDAP *ld );
-
-Parameters are:
-
-ld   The session handle.
-
-ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding
-from the directory, closing the connection, and freeing up the ld struc-
-ture before returning.   There is no server response to an unbind opera-
-tion.  ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if
-the request cannot be sent to the LDAP server).  After a call to
-ldap_unbind() or ldap_unbind_s(), the session handle ld is invalid.
-
-
-7.6.  Searching
-
-The following functions are used to search the LDAP directory, returning
-a requested set of attributes for each entry matched.  There are five
-variations.
-
-
-
-Expires: January 1998                                          [Page 13]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           int ldap_search_ext(
-                   LDAP            *ld,
-                   char            *base,
-                   int             scope,
-                   char            *filter,
-                   char            **attrs,
-                   int             attrsonly,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   struct timeval  *timeoutp,
-                   int             sizelimit,
-                   int             *msgidp
-           );
-
-           int ldap_search_ext_s(
-                   LDAP            *ld,
-                   char            *base,
-                   int             scope,
-                   char            *filter,
-                   char            **attrs,
-                   int             attrsonly,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   struct timeval  *timeoutp,
-                   int             sizelimit,
-                   LDAPMessage     **res
-           );
-
-           int ldap_search(
-                   LDAP    *ld,
-                   char    *base,
-                   int     scope,
-                   char    *filter,
-                   char    **attrs,
-                   int     attrsonly
-           );
-
-           int ldap_search_s(
-                   LDAP            *ld,
-                   char            *base,
-                   int             scope,
-                   char            *filter,
-                   char            **attrs,
-                   int             attrsonly,
-                   LDAPMessage     **res
-           );
-
-           int ldap_search_st(
-
-
-
-Expires: January 1998                                          [Page 14]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-                   LDAP            *ld,
-                   char            *base,
-                   int             scope,
-                   char            *filter,
-                   char            **attrs,
-                   int             attrsonly,
-                   struct timeval  *timeout,
-                   LDAPMessage     **res
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-base         The dn of the entry at which to start the search.
-
-scope        One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
-             or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
-             search.
-
-filter       A character string as described in [3], representing the
-             search filter.
-
-attrs        A NULL-terminated array of strings indicating which attri-
-             butes to return for each matching entry. Passing NULL for
-             this parameter causes all available attributes to be
-             retrieved.
-
-attrsonly    A boolean value that should be zero if both attribute types
-             and values are to be returned, non-zero if only types are
-             wanted.
-
-timeout      For the ldap_search_st() function, this specifies the local
-             search timeout value.  For the ldap_search_ext() and
-             ldap_search_ext_s() functions, this specifies both the
-             local search timeout value and the operation time limit
-             that is sent to the server within the search request.
-
-res          For the synchronous calls, this is a result parameter which
-             will contain the results of the search upon completion of
-             the call.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_search_ext() call succeeds.
-
-
-
-Expires: January 1998                                          [Page 15]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-There are three options in the session handle ld which potentially
-affect how the search is performed. They are:
-
-LDAP_OPT_SIZELIMIT
-             A limit on the number of entries to return from the search.
-             A value of zero means no limit.  Note that the value from
-             the session handle is ignored when using the
-             ldap_search_ext() or ldap_search_ext_s() functions.
-
-LDAP_OPT_TIMELIMIT
-             A limit on the number of seconds to spend on the search. A
-             value of zero means no limit.  Note that the value from the
-             session handle is ignored when using the ldap_search_ext()
-             or ldap_search_ext_s() functions.
-
-LDAP_OPT_DEREF
-             One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
-             (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
-             (0x03), specifying how aliases should be handled during the
-             search. The LDAP_DEREF_SEARCHING value means aliases should
-             be dereferenced during the search but not when locating the
-             base object of the search. The LDAP_DEREF_FINDING value
-             means aliases should be dereferenced when locating the base
-             object but not during the search.
-
-The ldap_search_ext() function initiates an asynchronous search opera-
-tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not.  See the section below on
-error handling for more information about possible errors and how to
-interpret them.  If successful, ldap_search_ext() places the message id
-of the request in *msgidp. A subsequent call to ldap_result(), described
-below, can be used to obtain the results from the search.  These results
-can be parsed using the result parsing routines described in detail
-later.
-
-Similar to ldap_search_ext(), the ldap_search() function initiates an
-asynchronous search operation and returns the message id of the opera-
-tion initiated.  As for ldap_search_ext(), a subsequent call to
-ldap_result(), described below, can be used to obtain the result of the
-bind. In case of error, ldap_search() will return -1, setting the ses-
-sion error parameters in the LDAP structure appropriately.
-
-The synchronous ldap_search_ext_s(), ldap_search_s(), and
-ldap_search_st() functions all return the result of the operation,
-either the constant LDAP_SUCCESS if the operation was successful, or
-another LDAP error code if it was not. See the section below on error
-handling for more information about possible errors and how to interpret
-them.  Entries returned from the search (if any) are contained in the
-
-
-
-Expires: January 1998                                          [Page 16]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-res parameter. This parameter is opaque to the caller.  Entries, attri-
-butes, values, etc., should be extracted by calling the parsing routines
-described below. The results contained in res should be freed when no
-longer in use by calling ldap_msgfree(), described later.
-
-The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
-server controls, client controls, and allow varying size and time limits
-to be easily specified for each search operation.  The ldap_search_st()
-function is identical to ldap_search_s() except that it takes an addi-
-tional parameter specifying a local timeout for the search.
-
-7.7.  Reading an Entry
-
-LDAP does not support a read operation directly. Instead, this operation
-is emulated by a search with base set to the DN of the entry to read,
-scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs
-contains the list of attributes to return.
-
-
-7.8.  Listing the Children of an Entry
-
-LDAP does not support a list operation directly. Instead, this operation
-is emulated by a search with base set to the DN of the entry to list,
-scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)".
-attrs contains the list of attributes to return for each child entry.
-
-7.9.  Comparing a Value Against an Entry
-
-The following routines are used to compare a given attribute value
-assertion against an LDAP entry.  There are four variations:
-
-           int ldap_compare_ext(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *attr,
-                   struct berval   *bvalue
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-           int ldap_compare_ext_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *attr,
-                   struct berval   *bvalue,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-
-
-
-Expires: January 1998                                          [Page 17]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           );
-
-           int ldap_compare(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *attr,
-                   char            *value
-           );
-
-           int ldap_compare_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *attr,
-                   char            *value
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry to compare against.
-
-attr         The attribute to compare against.
-
-bvalue       The attribute value to compare against those found in the
-             given entry. This parameter is used in the extended rou-
-             tines and is a pointer to a struct berval so it is possible
-             to compare binary values.
-
-value        A string attribute value to compare against, used by the
-             ldap_compare() and ldap_compare_s() functions.  Use
-             ldap_compare_ext() or ldap_compare_ext_s() if you need to
-             compare binary values.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_compare_ext() call succeeds.
-
-The ldap_compare_ext() function initiates an asynchronous compare opera-
-tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not.  See the section below on
-error handling for more information about possible errors and how to
-interpret them.  If successful, ldap_compare_ext() places the message id
-of the request in *msgidp. A subsequent call to ldap_result(), described
-below, can be used to obtain the result of the compare.
-
-
-
-Expires: January 1998                                          [Page 18]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-Similar to ldap_compare_ext(), the ldap_compare() function initiates an
-asynchronous compare operation and returns the message id of the opera-
-tion initiated.  As for ldap_compare_ext(), a subsequent call to
-ldap_result(), described below, can be used to obtain the result of the
-bind. In case of error, ldap_compare() will return -1, setting the ses-
-sion error parameters in the LDAP structure appropriately.
-
-The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
-return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
-See the section below on error handling for more information about pos-
-sible errors and how to interpret them.
-
-The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
-server controls and client controls.
-
-
-7.10.  Modifying an entry
-
-The following routines are used to modify an existing LDAP entry.  There
-are four variations:
-
-           typedef struct ldapmod {
-                   int             mod_op;
-                   char            *mod_type;
-                   union {
-                           char            **modv_strvals;
-                           struct berval   **modv_bvals;
-                   } mod_vals;
-           } LDAPMod;
-           #define mod_values      mod_vals.modv_strvals
-           #define mod_bvalues     mod_vals.modv_bvals
-
-           int ldap_modify_ext(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **mods,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-           int ldap_modify_ext_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **mods,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-
-
-
-Expires: January 1998                                          [Page 19]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           );
-
-           int ldap_modify(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **mods
-           );
-
-           int ldap_modify_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **mods
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry to modify.
-
-mods         A NULL-terminated array of modifications to make to the
-             entry.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_modify_ext() call succeeds.
-
-The fields in the LDAPMod structure have the following meanings:
-
-mod_op       The modification operation to perform. It should be one of
-             LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
-             LDAP_MOD_REPLACE (0x02).  This field also indicates the
-             type of values included in the mod_vals union. It is logi-
-             cally ORed with LDAP_MOD_BVALUES (0x80) to select the
-             mod_bvalues form. Otherwise, the mod_values form is used.
-
-mod_type     The type of the attribute to modify.
-
-mod_vals     The values (if any) to add, delete, or replace. Only one of
-             the mod_values or mod_bvalues variants should be used,
-             selected by ORing the mod_op field with the constant
-             LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
-             zero-terminated strings and mod_bvalues is a NULL-
-             terminated array of berval structures that can be used to
-             pass binary values such as images.
-
-
-
-Expires: January 1998                                          [Page 20]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-For LDAP_MOD_ADD modifications, the given values are added to  the
-entry, creating the attribute if necessary.
-
-For LDAP_MOD_DELETE modifications, the given values are deleted from the
-entry, removing the attribute if no values remain. If the entire attri-
-bute is to  be deleted, the mod_vals field should be set to NULL.
-
-For LDAP_MOD_REPLACE modifications, the attribute will have the listed
-values after the modification, having been created if necessary, or
-removed if the mod_vals field is NULL. All modifications are performed
-in the order in which they are listed.
-
-The ldap_modify_ext() function initiates an asynchronous modify opera-
-tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not.  See the section below on
-error handling for more information about possible errors and how to
-interpret them.  If successful, ldap_modify_ext() places the message id
-of the request in *msgidp. A subsequent call to ldap_result(), described
-below, can be used to obtain the result of the modify.
-
-Similar to ldap_modify_ext(), the ldap_modify() function initiates an
-asynchronous modify operation and returns the message id of the opera-
-tion initiated.  As for ldap_modify_ext(), a subsequent call to
-ldap_result(), described below, can be used to obtain the result of the
-modify. In case of error, ldap_modify() will return -1, setting the ses-
-sion error parameters in the LDAP structure appropriately.
-
-The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
-return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
-See the section below on error handling for more information about pos-
-sible errors and how to interpret them.
-
-The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
-server controls and client controls.
-
-
-7.11.  Modifying the Name of an Entry
-
-In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to
-change the name of an LDAP entry. They could only be used to change the
-least significant component of a name (the RDN or relative distinguished
-name). LDAPv3 provides the Modify DN protocol operation that allows more
-general name change access. The ldap_rename() and ldap_rename_s() rou-
-tines are used to change the name of an entry, and the use of the
-ldap_modrdn() and ldap_modrdn_s() routines is deprecated.
-
-           int ldap_rename(
-
-
-
-Expires: January 1998                                          [Page 21]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *newrdn,
-                   char            *newparent,
-                   int             deleteoldrdn,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-
-           );
-           int ldap_rename_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   char            *newrdn,
-                   char            *newparent,
-                   int             deleteoldrdn,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-           );
-
-   Use of the following routines is deprecated.
-
-           int ldap_modrdn(
-                   LDAP    *ld,
-                   char    *dn,
-                   char    *newrdn,
-                   int     deleteoldrdn
-           );
-           int ldap_modrdn_s(
-                   LDAP    *ld,
-                   char    *dn,
-                   char    *newrdn,
-                   int     deleteoldrdn
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry whose DN is to be changed.
-
-newrdn       The new RDN to give the entry.
-
-newparent    The new parent, or superior entry.  If this parameter is
-             NULL, only the RDN of the entry is changed.  The root DN
-             may be specified by passing a zero length string, "".  The
-             newparent parameter should always be NULL when using ver-
-             sion 2 of the LDAP protocol; otherwise the server's
-
-
-
-Expires: January 1998                                          [Page 22]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-             behavior is undefined.
-
-deleteoldrdn This parameter only has meaning on the rename routines if
-             newrdn is different than the old RDN. It is a boolean
-             value, if non-zero indicating that the old RDN value(s)
-             should be removed, if zero indicating that the old RDN
-             value(s) should be retained as non-distinguished values of
-             the entry.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_rename() call succeeds.
-
-The ldap_rename() function initiates an asynchronous modify DN operation
-and returns the constant LDAP_SUCCESS if the request was successfully
-sent, or another LDAP error code if not.  See the section below on error
-handling for more information about possible errors and how to interpret
-them.  If successful, ldap_rename() places the DN message id of the
-request in *msgidp. A subsequent call to ldap_result(), described below,
-can be used to obtain the result of the rename.
-
-The synchronous ldap_rename_s() returns the result of the operation,
-either the constant LDAP_SUCCESS if the operation was successful, or
-another LDAP error code if it was not.  See the section below on error
-handling for more information about possible errors and how to interpret
-them.
-
-The ldap_rename() and ldap_rename_s() functions both support LDAPv3
-server controls and client controls.
-
-
-7.12.  Adding an entry
-
-The following functions are used to add entries to the LDAP directory.
-There are four variations:
-
-           int ldap_add_ext(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **attrs,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-
-
-
-Expires: January 1998                                          [Page 23]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           int ldap_add_ext_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **attrs,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-           );
-
-           int ldap_add(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **attrs
-           );
-
-           int ldap_add_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPMod         **attrs
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry to add.
-
-attrs        The entry's attributes, specified using the LDAPMod struc-
-             ture defined for ldap_modify(). The mod_type and mod_vals
-             fields should be filled in.  The mod_op field is ignored
-             unless ORed with the constant LDAP_MOD_BVALUES, used to
-             select the mod_bvalues case of the mod_vals union.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_add_ext() call succeeds.
-
-Note that the parent of the entry being added must already exist or the
-parent must be empty (i.e., equal to the root DN) for an add to succeed.
-
-The ldap_add_ext() function initiates an asynchronous add operation and
-returns the constant LDAP_SUCCESS if the request was successfully sent,
-or another LDAP error code if not.  See the section below on error han-
-dling for more information about possible errors and how to interpret
-them.  If successful, ldap_add_ext() places the message id of the
-request in *msgidp. A subsequent call to ldap_result(), described below,
-
-
-
-Expires: January 1998                                          [Page 24]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-can be used to obtain the result of the add.
-
-Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
-chronous add operation and returns the message id of the operation ini-
-tiated.  As for ldap_add_ext(), a subsequent call to ldap_result(),
-described below, can be used to obtain the result of the add. In case of
-error, ldap_add() will return -1, setting the session error parameters
-in the LDAP structure appropriately.
-
-The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
-the result of the operation, either the constant LDAP_SUCCESS if the
-operation was successful, or another LDAP error code if it was not.  See
-the section below on error handling for more information about possible
-errors and how to interpret them.
-
-The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
-controls and client controls.
-
-
-
-7.13.  Deleting an entry
-
-The following functions are used to delete a leaf entry from the LDAP
-directory.  There are four variations:
-
-           int ldap_delete_ext(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-           int ldap_delete_ext_s(
-                   LDAP            *ld,
-                   char            *dn,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-           );
-
-           int ldap_delete(
-                   LDAP            *ld,
-                   char            *dn
-           );
-
-           int ldap_delete_s(
-                   LDAP            *ld,
-                   char            *dn
-
-
-
-Expires: January 1998                                          [Page 25]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-dn           The name of the entry to delete.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_delete_ext() call succeeds.
-
-Note that the entry to delete must be a leaf entry (i.e., it must have
-no children). Deletion of entire subtrees in a single operation is not
-supported by LDAP.
-
-The ldap_delete_ext() function initiates an asynchronous delete opera-
-tion and returns the constant LDAP_SUCCESS if the request was success-
-fully sent, or another LDAP error code if not.  See the section below on
-error handling for more information about possible errors and how to
-interpret them.  If successful, ldap_delete_ext() places the message id
-of the request in *msgidp. A subsequent call to ldap_result(), described
-below, can be used to obtain the result of the delete.
-
-Similar to ldap_delete_ext(), the ldap_delete() function initiates an
-asynchronous delete operation and returns the message id of the opera-
-tion initiated.  As for ldap_delete_ext(), a subsequent call to
-ldap_result(), described below, can be used to obtain the result of the
-delete. In case of error, ldap_delete() will return -1, setting the ses-
-sion error parameters in the LDAP structure appropriately.
-
-The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
-return the result of the operation, either the constant LDAP_SUCCESS if
-the operation was successful, or another LDAP error code if it was not.
-See the section below on error handling for more information about pos-
-sible errors and how to interpret them.
-
-The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
-server controls and client controls.
-
-
-7.14.  Extended Operations
-
-The ldap_extended_operation() and ldap_extended_operation_s() routines
-allow extended LDAP operations to be passed to the server, providing a
-
-
-
-Expires: January 1998                                          [Page 26]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-general protocol extensibility mechanism.
-
-           int ldap_extended_operation(
-                   LDAP            *ld,
-                   char            *exoid,
-                   struct berval   *exdata,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   int             *msgidp
-           );
-
-           int ldap_extended_operation_s(
-                   LDAP            *ld,
-                   char            *exoid,
-                   struct berval   *exdata,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls,
-                   char            **retoidp,
-                   struct berval   **retdatap
-           );
-
-Parameters are:
-
-ld           The session handle.
-
-requestoid   The dotted-OID text string naming the request.
-
-requestdata  The arbitrary data required by the operation (if NULL, no
-             data is sent to the server).
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-msgidp       This result parameter will be set to the message id of the
-             request if the ldap_extended_operation() call succeeds.
-
-retoidp      Pointer to a character string that will be set to an allo-
-             cated, dotted-OID text string returned by the server.  This
-             string should be disposed of using the ldap_memfree() func-
-             tion.  If no OID was returned, *retoidp is set to NULL.
-
-retdatap     Pointer to a berval structure pointer that will be set an
-             allocated copy of the data returned by the server.  This
-             struct berval should be disposed of using ber_bvfree().  If
-             no data is returned, *retdatap is set to NULL.
-
-The ldap_extended_operation() function initiates an asynchronous
-
-
-
-Expires: January 1998                                          [Page 27]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-extended operation and returns the constant LDAP_SUCCESS if the request
-was successfully sent, or another LDAP error code if not.  See the sec-
-tion below on error handling for more information about possible errors
-and how to interpret them.  If successful, ldap_extended_operation()
-places the message id of the request in *msgidp. A subsequent call to
-ldap_result(), described below, can be used to obtain the result of the
-extended operation which can be passed to ldap_parse_extended_result()
-to obtain the OID and data contained in the response.
-
-The synchronous ldap_extended_operation_s() function returns the result
-of the operation, either the constant LDAP_SUCCESS if the operation was
-successful, or another LDAP error code if it was not.  See the section
-below on error handling for more information about possible errors and
-how to interpret them.  The retoid and retdata parameters are filled in
-with the OID and data from the response.  If no OID or data was
-returned, these parameters are set to NULL.
-
-The ldap_extended_operation() and ldap_extended_operation_s() functions
-both support LDAPv3 server controls and client controls.
-
-
-8.  Abandoning An Operation
-
-The following calls are used to abandon an operation in progress:
-
-           int ldap_abandon_ext(
-                   LDAP            *ld,
-                   int             msgid,
-                   LDAPControl     **serverctrls,
-                   LDAPControl     **clientctrls
-           );
-
-           int ldap_abandon(
-                   LDAP            *ld,
-                   int             msgid
-           );
-
-
-ld           The session handle.
-
-msgid        The message id of the request to be abandoned.
-
-serverctrls  List of LDAP server controls.
-
-clientctrls  List of client controls.
-
-ldap_abandon_ext() abandons the operation with message id msgid and
-returns the constant LDAP_SUCCESS if the abandon was successful or
-
-
-
-Expires: January 1998                                          [Page 28]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-another LDAP error code if not.  See the section below on error handling
-for more information about possible errors and how to interpret them.
-
-ldap_abandon() is identical to ldap_abandon_ext() except that it returns
-zero if the abandon was successful, -1 otherwise and does not support
-LDAPv3 server controls or client controls.
-
-After a successful call to ldap_abandon() or ldap_abandon_ext(), results
-with the given message id are never returned from a subsequent call to
-ldap_result().  There is no server response to LDAP abandon operations.
-
-
-9.  Obtaining Results and Peeking Inside LDAP Messages
-
-ldap_result() is used to obtain the result of a previous asynchronously
-initiated operation. Note that depending on how it is called,
-ldap_result() may actually return a list or "chain" of messages.
-
-ldap_msgfree() frees the results obtained from a previous call to
-ldap_result(), or a synchronous search routine.
-
-ldap_msgtype() returns the type of an LDAP message.  ldap_msgid()
-returns the message ID of an LDAP message.
-
-           int ldap_result(
-                   LDAP            *ld,
-                   int             msgid,
-                   int             all,
-                   struct timeval  *timeout,
-                   LDAPMessage     **res
-           );
-
-           int ldap_msgfree( LDAPMessage *res );
-
-           int ldap_msgtype( LDAPMessage *res );
-
-           int ldap_msgid( LDAPMessage *res );
-
-Parameters are:
-
-ld       The session handle.
-
-msgid    The message id of the operation whose results are to be
-         returned, or the constant LDAP_RES_ANY (-1) if any result is
-         desired.
-
-all      Specifies how many messages will be retrieved in a single call
-         to ldap_result().  This parameter only has meaning for search
-
-
-
-Expires: January 1998                                          [Page 29]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-         results.  Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
-         message at a time.  Pass LDAP_MSG_ALL (0x01) to request that
-         all results of a search be received before returning all
-         results in a single chain.  Pass LDAP_MSG_RECEIVED (0x02) to
-         indicate that all results retrieved so far should be returned
-         in the result chain.
-
-timeout  A timeout specifying how long to wait for results to be
-         returned.  A NULL value causes ldap_result() to block until
-         results are available.  A timeout value of zero seconds speci-
-         fies a polling behavior.
-
-res      For ldap_result(), a result parameter that will contain the
-         result(s) of the operation. For ldap_msgfree(), the result
-         chain to be freed, obtained from a previous call to
-         ldap_result(), ldap_search_s(), or ldap_search_st().
-
-Upon successful completion, ldap_result() returns the type of the first
-result returned in the res parameter. This will be one of the following
-constants.
-
-             LDAP_RES_BIND (0x61)
-             LDAP_RES_SEARCH_ENTRY (0x64)
-             LDAP_RES_SEARCH_REFERENCE (0x73)      -- new in LDAPv3
-             LDAP_RES_SEARCH_RESULT (0x65)
-             LDAP_RES_MODIFY (0x67)
-             LDAP_RES_ADD (0x69)
-             LDAP_RES_DELETE (0x6B)
-             LDAP_RES_MODDN (0x6D)
-             LDAP_RES_COMPARE (0x6F)
-             LDAP_RES_EXTENDED (0x78)              -- new in LDAPv3
-
-ldap_result() returns 0 if the timeout expired and -1 if an error
-occurs, in which case the error parameters of the LDAP session handle
-will be set accordingly.
-
-ldap_msgfree() frees the result structure pointed to by res and returns
-the type of the message it freed.
-
-ldap_msgtype() returns the type of the LDAP message it is passed as a
-parameter. The type will be one of the types listed above, or -1 on
-error.
-
-ldap_msgid() returns the message ID associated with the LDAP message
-passed as a parameter.
-
-
-
-
-
-
-Expires: January 1998                                          [Page 30]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-10.  Handling Errors and Parsing Results
-
-The following calls are used to extract information from results and
-handle errors returned by other LDAP API routines.
-
-           int ldap_parse_result(
-                   LDAP            *ld,
-                   LDAPMessage     *res,
-                   int             *errcodep,
-                   char            **matcheddnp,
-                   char            **errmsgp,
-                   char            ***referralsp,
-                   LDAPControl     ***serverctrlsp,
-                   int             freeit
-           );
-
-           int ldap_parse_sasl_bind_result(
-                   LDAP            *ld,
-                   LDAPMessage     *res,
-                   struct berval   **servercredp,
-                   int             freeit
-           );
-
-           int ldap_parse_extended_result(
-                   LDAP            *ld,
-                   LDAPMessage     *res,
-                   char            **resultoidp,
-                   struct berval   **resultdata,
-                   int             freeit
-           );
-
-           char *ldap_err2string( int err );
-
-   The use of the following routines is deprecated.
-
-           int ldap_result2error(
-                   LDAP            *ld,
-                   LDAPMessage     *res,
-                   int             freeit
-           );
-
-           void ldap_perror( LDAP *ld, char *msg );
-
-Parameters are:
-
-ld           The session handle.
-
-res          The result of an LDAP operation as returned by
-
-
-
-Expires: January 1998                                          [Page 31]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-             ldap_result() or one of the synchronous API operation
-             calls.
-
-errcodep     This result parameter will be filled in with the LDAP error
-             code field from the LDAPResult message.  This is the indi-
-             cation from the server of the outcome of the operation.
-             NULL may be passed to ignore this field.
-
-matcheddnp   In the case of a return of LDAP_NO_SUCH_OBJECT, this result
-             parameter will be filled in with a DN indicating how much
-             of the name in the request was recognized. NULL may be
-             passed to ignore this field.  The matched DN string should
-             be freed by calling ldap_memfree() which is described later
-             in this document.
-
-errmsgp      This result parameter will be filled in with the contents
-             of the error message field from the LDAPResult message.
-             The error message string should be freed by calling
-             ldap_memfree() which is described later in this document.
-             NULL may be passed to ignore this field.
-
-referralsp   This result parameter will be filled in with the contents
-             of the referrals field from the LDAPResult message, indi-
-             cating zero or more alternate LDAP servers where the
-             request should be retried.  The referrals array should be
-             freed by calling ldap_value_free() which is described later
-             in this document.  NULL may be passed to ignore this field.
-
-serverctrlsp This result parameter will be filled in with an allocated
-             array of controls copied out of the LDAPResult message.
-             The control array should be freed by calling
-             ldap_controls_free() which was described earlier.
-
-freeit       A boolean that determines whether the res parameter is
-             disposed of or not.  Pass any non-zero value to have these
-             routines free res after extracting the requested informa-
-             tion.  This is provided as a convenience; you can also use
-             ldap_msgfree() to free the result later.
-
-servercredp  For SASL bind results, this result parameter will be filled
-             in with the credentials passed back by the server for
-             mutual authentication, if given. An allocated berval struc-
-             ture is returned that should be disposed of by calling
-             ldap_ber_free().  NULL may be passed to ignore this field.
-
-resultoidp   For extended results, this result parameter will be filled
-             in with the dotted-OID text representation of the name of
-             the extended operation response.  This string should be
-
-
-
-Expires: January 1998                                          [Page 32]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-             disposed of by calling ldap_memfree().  NULL may be passed
-             to ignore this field.
-
-resultdatap  For extended results, this result parameter will be filled
-             in with a pointer to a struct berval containing the data in
-             the extended operation response.  It should be disposed of
-             by calling ldap_ber_free(). NULL may be passed to ignore
-             this field.
-
-err          For ldap_err2string(), an LDAP error code, as returned by
-             ldap_result2error() or another LDAP API call.
-
-Additional parameters for the deprecated routines are not described.
-Interested readers are referred to RFC 1823.
-
-All of the ldap_parse_*_result() routines skip over messages of type
-LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
-result message to parse.  They return the constant LDAP_SUCCESS if the
-result was successfully parsed and another LDAP error code if not.  Note
-that the LDAP error code that indicates the outcome of the operation
-performed by the server is placed in the errcodep ldap_parse_result()
-parameter.
-
-ldap_err2string() is used to convert a numeric LDAP error code, as
-returned by one of the ldap_parse_*_result() routines, or one of the
-synchronous API operation calls, into an informative NULL-terminated
-character string message describing the error.  It returns a pointer to
-static data.
-
-
-11.  Stepping Through a List of Results
-
-The ldap_first_message() and ldap_next_message() routines are used to
-step through the list of messages in a result chain returned by
-ldap_result().  For search operations, the result chain may actually
-include referral messages, entry messages, and result messages.
-ldap_count_messages() is used to count the number of messages returned.
-The ldap_msgtype() function, described above, can be used to distinguish
-between the different message types.
-
-           LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
-
-           LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
-
-           int ldap_count_messages( LDAP *ld, LDAPMessage *res );
-
-Parameters are:
-
-
-
-
-Expires: January 1998                                          [Page 33]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-ld     The session handle.
-
-res    The result chain, as obtained by a call to one of the synchronous
-       search routines or ldap_result().
-
-msg    The message returned by a previous call to ldap_first_message()
-       or ldap_next_message().
-
-ldap_first_message() and ldap_next_message() will return NULL when no
-more messages exist in the result set to be returned.  NULL is also
-returned if an error occurs while stepping through the entries, in which
-case the error parameters in the session handle ld will be set to indi-
-cate the error.
-
-ldap_count_messages() returns the number of messages contained in a
-chain of results. It can also be used to count the number of messages
-that remain in a chain if called with a message, entry, or reference
-returned by ldap_first_message(), ldap_next_message(),
-ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
-ldap_next_reference().
-
-
-12.  Parsing Search Results
-
-The following calls are used to parse the entries and references
-returned by ldap_search() and friends. These results are returned in an
-opaque structure that should only be accessed by calling the routines
-described below. Routines are provided to step through the entries and
-references returned, step through the attributes of an entry, retrieve
-the name of an entry, and retrieve the values associated with a given
-attribute in an entry.
-
-
-12.1.  Stepping Through a List of Entries
-
-The ldap_first_entry() and ldap_next_entry() routines are used to step
-through and retrieve the list of entries from a search result chain.
-The ldap_first_reference() and ldap_next_reference() routines are used
-to step through and retrieve the list of continuation references from a
-search result chain.  ldap_count_entries() is used to count the number
-of entries returned. ldap_count_references() is used to count the number
-of references returned.
-
-           LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
-
-           LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
-
-           LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
-
-
-
-Expires: January 1998                                          [Page 34]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
-
-           int ldap_count_entries( LDAP *ld, LDAPMessage *res );
-
-           int ldap_count_references( LDAP *ld, LDAPMessage *res );
-
-Parameters are:
-
-ld     The session handle.
-
-res    The search result, as obtained by a call to one of the synchro-
-       nous search routines or ldap_result().
-
-entry  The entry returned by a previous call to ldap_first_entry() or
-       ldap_next_entry().
-
-ldap_first_entry() and ldap_next_entry() will return NULL when no more
-entries or references exist in the result set to be returned.  NULL is
-also returned if an error occurs while stepping through the entries, in
-which case the error parameters in the session handle ld will be set to
-indicate the error.
-
-ldap_count_entries() returns the number of entries contained in a chain
-of entries. It can also be used to count the number of entries that
-remain in a chain if called with a message, entry or reference returned
-by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
-ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
-
-ldap_count_references() returns the number of references contained in a
-chain of search results. It can also be used to count the number of
-references that remain in a chain.
-
-
-12.2.  Stepping Through the Attributes of an Entry
-
-The ldap_first_attribute() and ldap_next_attribute() calls are used to
-step through the list of attribute types returned with an entry.
-
-           char *ldap_first_attribute(
-                   LDAP            *ld,
-                   LDAPMessage     *entry,
-                   BerElement      **ptr
-           );
-
-           char *ldap_next_attribute(
-                   LDAP            *ld,
-                   LDAPMessage     *entry,
-                   BerElement      *ptr
-
-
-
-Expires: January 1998                                          [Page 35]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           );
-
-           void ldap_memfree( char *mem );
-
-Parameters are:
-
-ld     The session handle.
-
-entry  The entry whose attributes are to be stepped through, as returned
-       by ldap_first_entry() or ldap_next_entry().
-
-ptr    In ldap_first_attribute(), the address of a pointer used inter-
-       nally to keep track of the current position in the entry. In
-       ldap_next_attribute(), the pointer returned by a previous call to
-       ldap_first_attribute().
-
-mem    A pointer to memory allocated by the LDAP library, such as the
-       attribute names returned by ldap_first_attribute() and
-       ldap_next_attribute, or the DN returned by ldap_get_dn().
-
-ldap_first_attribute() and ldap_next_attribute() will return NULL when
-the end of the attributes is reached, or if there is an error, in which
-case the error parameters in the session handle ld will be set to indi-
-cate the error.
-
-Both routines return a pointer to an allocated buffer containing the
-current attribute name. This should be freed when no longer in use by
-calling ldap_memfree().
-
-ldap_first_attribute() will allocate and return in ptr a pointer to a
-BerElement used to keep track of the current position. This pointer
-should be passed in subsequent calls to ldap_next_attribute() to step
-through the entry's attributes. After a set of calls to
-ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it
-should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very
-important to pass the second parameter as 0 (zero) in this call.
-
-The attribute names returned are suitable for passing in a call to
-ldap_get_values() and friends to retrieve the associated values.
-
-
-12.3.  Retrieving the Values of an Attribute
-
-ldap_get_values() and ldap_get_values_len() are used to retrieve the
-values of a given attribute from an entry. ldap_count_values() and
-ldap_count_values_len() are used to count the returned values.
-ldap_value_free() and ldap_value_free_len() are used to free the values.
-
-
-
-
-Expires: January 1998                                          [Page 36]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           char **ldap_get_values(
-                   LDAP            *ld,
-                   LDAPMessage     *entry,
-                   char            *attr
-           );
-
-           struct berval **ldap_get_values_len(
-                   LDAP            *ld,
-                   LDAPMessage     *entry,
-                   char            *attr
-           );
-
-           int ldap_count_values( char **vals );
-
-           int ldap_count_values_len( struct berval **vals );
-
-           int ldap_value_free( char **vals );
-
-           int ldap_value_free_len( struct berval **vals );
-
-Parameters are:
-
-ld     The session handle.
-
-entry  The entry from which to retrieve values, as returned by
-       ldap_first_entry() or ldap_next_entry().
-
-attr   The attribute whose values are to be retrieved, as returned by
-       ldap_first_attribute() or ldap_next_attribute(), or a caller-
-       supplied string (e.g., "mail").
-
-vals   The values returned by a previous call to ldap_get_values() or
-       ldap_get_values_len().
-
-Two forms of the various calls are provided. The first form is only
-suitable for use with non-binary character string data. The second _len
-form is used with any kind of data.
-
-Note that the values returned are dynamically allocated and should be
-freed by calling either ldap_value_free() or ldap_value_free_len() when
-no longer in use.
-
-
-12.4.  Retrieving the name of an entry
-
-ldap_get_dn() is used to retrieve the name of an entry.
-ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
-into its component parts. ldap_dn2ufn() is used to convert the name into
-
-
-
-Expires: January 1998                                          [Page 37]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-a more "user friendly" format.
-
-           char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
-
-           char **ldap_explode_dn( char *dn, int notypes );
-
-           char **ldap_explode_rdn( char *rdn, int notypes );
-
-           char *ldap_dn2ufn( char *dn );
-
-Parameters are:
-
-ld      The session handle.
-
-entry   The entry whose name is to be retrieved, as returned by
-        ldap_first_entry() or ldap_next_entry().
-
-dn      The dn to explode, such as returned by ldap_get_dn().
-
-rdn     The rdn to explode, such as returned in the components of the
-        array returned by ldap_explode_dn().
-
-notypes A boolean parameter, if non-zero indicating that the dn or rdn
-        components should have their type information stripped off
-        (i.e., "cn=Babs" would become "Babs").
-
-ldap_get_dn() will return NULL if there is some error parsing the dn,
-setting error parameters in the session handle ld to indicate the error.
-It returns a pointer to malloc'ed space that the caller should free by
-calling ldap_memfree() when it is no longer in use.  Note the format of
-the DNs returned is given by [4].
-
-ldap_explode_dn() returns a NULL-terminated char * array containing the
-RDN components of the DN supplied, with or without types as indicated by
-the notypes parameter. The array returned should be freed when it is no
-longer in use by calling ldap_value_free().
-
-ldap_explode_rdn() returns a NULL-terminated char * array containing the
-components of the RDN supplied, with or without types as indicated by
-the notypes parameter. The array returned should be freed when it is no
-longer in use by calling ldap_value_free().
-
-ldap_dn2ufn() converts the DN into the user friendly format described in
-[5]. The UFN returned is malloc'ed space that should be freed by a call
-to ldap_memfree() when no longer in use.
-
-
-
-
-
-
-Expires: January 1998                                          [Page 38]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-13.  Encoded ASN.1 Value Manipulation
-
-This section describes routines which may be used to encode and decode
-BER-encoded ASN.1 values, which are often used inside of control and
-extension values.
-
-With the exceptions of two new functions ber_flatten() and ber_init(),
-these functions are compatible with the University of Michigan LDAP 3.3
-implementation of BER.
-
-
-13.1.  General
-
-           struct berval {
-                   unsigned long   bv_len;
-                   char            *bv_val;
-           };
-
-A struct berval contains a sequence of bytes and an indication of its
-length.  The bv_val is not null terminated.  bv_len must always be a
-nonnegative number.  Applications may allocate their own berval struc-
-tures.
-
-           typedef struct berelement {
-                   /* opaque */
-           } BerElement;
-
-The BerElement structure contains not only a copy of the encoded value,
-but also state information used in encoding or decoding.  Applications
-cannot allocate their own BerElement structures.  The internal state is
-neither thread-specific nor locked, so two threads should not manipulate
-the same BerElement value simultaneously.
-
-A single BerElement value cannot be used for both encoding and decoding.
-
-           void ber_bvfree ( struct berval *bv);
-
-ber_bvfree() frees a berval returned from this API.  Both the bv->bv_val
-string and the berval itself are freed.  Applications should not use
-ber_bvfree() with bervals which the application has allocated.
-
-           void ber_bvecfree ( struct berval **bv );
-
-ber_bvecfree() frees an array of bervals returned from this API.  Each
-of the bervals in the array are freed using ber_bvfree(), then the array
-itself is freed.
-
-           struct berval *ber_bvdup (struct berval *bv );
-
-
-
-Expires: January 1998                                          [Page 39]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-ber_bvdup() returns a copy of a berval.  The bv_val field in the
-returned berval points to a different area of memory as the bv_val field
-in the argument berval.  The null pointer is returned on error (e.g. out
-of memory).
-
-           void ber_free ( BerElement *ber, int fbuf );
-
-ber_free() frees a BerElement which is returned from the API calls
-ber_alloc_t() or ber_init().  Each BerElement must be freed by the
-caller.  The second argument fbuf should always be set to 1.
-
-
-13.2.  Encoding
-
-           BerElement *ber_alloc_t(int options);
-
-ber_alloc_t() constructs and returns BerElement.  The null pointer is
-returned on error.  The options field contains a bitwise-or of options
-which are to be used when generating the encoding of this BerElement.
-One option is defined and must always be supplied:
-
-           #define LBER_USE_DER 0x01
-
-When this option is present, lengths will always be encoded in the
-minimum number of octets.  Note that this option does not cause values
-of sets and sequences to be rearranged in tag and byte order, so these
-functions are not suitable for generating DER output as defined in X.509
-and X.680.
-
-Unrecognized option bits are ignored.
-
-The BerElement returned by ber_alloc_t() is initially empty.  Calls to
-ber_printf() will append bytes to the end of the ber_alloc_t().
-
-           int ber_printf(BerElement *ber, char *fmt, ... )
-
-The ber_printf() routine is used to encode a BER element in much the
-same way that sprintf() works.  One important difference, though, is
-that state information is kept in the ber argument so that multiple
-calls can be made to ber_printf() to append to the end of the BER ele-
-ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
-ber_printf() interprets and formats its arguments according to the for-
-mat string fmt.  ber_printf() returns -1 if there is an error during
-encoding.  As with sprintf(), each character in fmt refers to an argu-
-ment to ber_printf().
-
-The format string can contain the following format characters:
-
-
-
-
-Expires: January 1998                                          [Page 40]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-'t'     Tag.  The next argument is an int specifying the tag to override
-        the next element to be written to the ber.  This works across
-        calls.  The int value must contain the tag class, constructed
-        bit, and tag value.  The tag value must fit in a single octet
-        (tag value is less than 32).  For example, a tag of "[3]" for a
-        constructed type is 0xA3.
-
-'b'     Boolean.  The next argument is an int, containing either 0 for
-        FALSE or 0xff for TRUE.  A boolean element is output.  If this
-        format character is not preceded by the 't' format modifier, the
-        tag 0x01 is used for the element.
-
-'i'     Integer.  The next argument is an int, containing the integer in
-        the host's byte order.  An integer element is output. If this
-        format character is not preceded by the 't' format modifier, the
-        tag 0x02 is used for the element.
-
-'X'     Bitstring.  The next two arguments are a char * pointer to the
-        start of the bitstring, followed by an int containing the number
-        of bits in the bitstring.  A bitstring element is output, in
-        primitive form.  If this format character is not preceded by the
-        't' format modifier, the tag 0x03 is used for the element.
-
-'n'     Null.  No argument is required.  An ASN.1 NULL element is out-
-        put.  If this format character is not preceded by the 't' format
-        modifier, the tag 0x05 is used for the element.
-
-'o'     Octet string.  The next two arguments are a char *, followed by
-        an int with the length of the string.  The string may contain
-        null bytes and need not by null-terminated.   An octet string
-        element is output, in primitive form.  If this format character
-        is not preceded by the 't' format modifier, the tag 0x04 is used
-        for the element.
-
-'s'     Octet string.  The next argument is a char * pointing to a
-        null-terminated string.  An octet string element in primitive
-        form is output, which does not include the trailing ' ' byte. If
-        this format character is not preceded by the 't' format modif-
-        ier, the tag 0x04 is used for the element.
-
-'v'     Several octet strings.  The next argument is a char **, an array
-        of char * pointers to null-terminated strings.  The last element
-        in the array must be a null pointer. The octet strings do not
-        include the trailing SEQUENCE OF octet strings.  The 't' format
-        modifier cannot be used with this format character.
-
-'V'     Several octet strings.  A null-terminated array of berval *'s is
-        supplied. Note that a construct like '{V}' is required to get an
-
-
-
-Expires: January 1998                                          [Page 41]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-        actual SEQUENCE OF octet strings. The 't' format modifier cannot
-        be used with this format character.
-
-'{'     Begin sequence.  No argument is required.  If this format char-
-        acter is not preceded by the 't' format modifier, the tag 0x30
-        is used.
-
-'}'     End sequence.  No argument is required.  The 't' format modifier
-        cannot be used with this format character.
-
-'['     Begin set.  No argument is required.  If this format character
-        is not preceded by the 't' format modifier, the tag 0x31 is
-        used.
-
-']'     End set.  No argument is required.  The 't' format modifier can-
-        not be used with this format character.
-
-Each use of a '{' format character must be matched by a '}' character,
-either later in the format string, or in the format string of a subse-
-quent call to ber_printf() for that BerElement.  The same applies to the
-'[' and
-
-Sequences and sets nest, and implementations of this API must maintain
-internal state to be able to properly calculate the lengths.
-
-           int ber_flatten (BerElement *ber, struct berval **bvPtr);
-
-The ber_flatten routine allocates a struct berval whose contents are a
-BER encoding taken from the ber argument. The bvPtr pointer points to
-the returned berval, which must be freed using ber_bvfree().  This rou-
-tine returns 0 on success and -1 on error.
-
-The ber_flatten API call is not present in U-M LDAP 3.3.
-
-The use of ber_flatten on a BerElement in which all '{' and '}' format
-modifiers have not been properly matched can result in a berval whose
-contents are not a valid BER encoding.
-
-
-13.3.  Encoding Example
-
-The following is an example of encoding the following ASN.1 data type:
-
-      Example1Request ::= SEQUENCE {
-           s     OCTET STRING, -- must be printable
-           val1  INTEGER,
-           val2  [0] INTEGER DEFAULT 0
-      }
-
-
-
-Expires: January 1998                                          [Page 42]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-      int encode_example1(char *s,int val1,int val2,struct berval **bvPtr)
-      {
-           BerElement *ber;
-           int rc;
-
-           ber = ber_alloc_t(LBER_USE_DER);
-
-           if (ber == NULL) return -1;
-
-           if (ber_printf(ber,"{si",s,val1) == -1) {
-                   ber_free(ber,1);
-                   return -1;
-           }
-
-           if (val2 != 0) {
-                   if (ber_printf(ber,"ti",0x80,val2) == -1) {
-                           ber_free(ber,1);
-                           return -1;
-                   }
-           }
-
-           if (ber_printf(ber,"}") == -1) {
-                   ber_free(ber,1);
-                   return -1;
-           }
-
-           rc = ber_flatten(ber,bvPtr);
-           ber_free(ber,1);
-           return -1;
-      }
-
-
-13.4.  Decoding
-
-The following two symbols are available to applications.
-
-           #define LBER_ERROR   0xffffffffL
-           #define LBER_DEFAULT 0xffffffffL
-
-           BerElement *ber_init (struct berval *bv);
-
-The ber_init functions construct BerElement and returns a new BerElement
-containing a copy of the data in the bv argument.  ber_init returns the
-null pointer on error.
-
-           unsigned long ber_scanf (BerElement *ber, char *fmt, ... );
-
-The ber_scanf() routine is used to decode a BER element in much the same
-
-
-
-Expires: January 1998                                          [Page 43]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-way that sscanf() works.  One important difference, though, is that some
-state information is kept with the ber argument so that multiple calls
-can be made to ber_scanf() to sequentially read from the BER element.
-The ber argument must be a pointer to a BerElement returned by
-ber_init().  ber_scanf interprets the bytes according to the format
-string fmt, and stores the results in its additional arguments.
-ber_scanf() returns LBER_ERROR on error, and a nonnegative number on
-success.
-
-The format string contains conversion specifications which are used to
-direct the interpretation of the BER element.  The format string can
-contain the following characters:
-
-'a'     Octet string.  A char ** argument should be supplied.  Memory is
-        allocated, filled with the contents of the octet string, null-
-        terminated, and the pointer to the string is stored in the argu-
-        ment.  The returned value must be freed using ldap_memfree.  The
-        tag of the element must indicate the primitive form (constructed
-        strings are not supported) but is otherwise ignored and dis-
-        carded during the decoding.  This format cannot be used with
-        octet strings which could contain null bytes.
-
-'O'     Octet string.  A struct berval ** argument should be supplied,
-        which upon return points to a allocated struct berval containing
-        the octet string and its length.  ber_bvfree() must be called to
-        free the allocated memory.  The tag of the element must indicate
-        the primitive form (constructed strings are not supported) but
-        is otherwise ignored during the decoding.
-
-'b'     Boolean.  A pointer to an int should be supplied. The int value
-        stored will be 0 for FALSE or nonzero for TRUE.  The tag of the
-        element must indicate the primitive form but is otherwise
-        ignored during the decoding.
-
-'i'     Integer.  A pointer to an int should be supplied. The int value
-        stored will be in host byte order.  The tag of the element must
-        indicate the primitive form but is otherwise ignored during the
-        decoding.  ber_scanf() will return an error if the integer can-
-        not be stored in an int.
-
-'B'     Bitstring.  A char ** argument should be supplied which will
-        point to the allocated bits, followed by an unsigned long *
-        argument, which will point to the length (in bits) of the bit-
-        string returned.  ldap_memfree must be called to free the bit-
-        string.  The tag of the element must indicate the primitive form
-        (constructed bitstrings are not supported) but is otherwise
-        ignored during the decoding.
-
-
-
-
-Expires: January 1998                                          [Page 44]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-'n'     Null.  No argument is required.  The element is simply skipped
-        if it is recognized as a zero-length element.  The tag is
-        ignored.
-
-'v'     Several octet strings.  A char *** argument should be supplied,
-        which upon return points to a allocated null-terminated array of
-        char *'s containing the octet strings.  NULL is stored if the
-        sequence is empty.  ldap_memfree must be called to free each
-        element of the array and the array itself.  The tag of the
-        sequence and of the octet strings are ignored.
-
-'V'     Several octet strings (which could contain null bytes).  A
-        struct berval *** should be supplied, which upon return points
-        to a allocated null-terminated array of struct berval *'s con-
-        taining the octet strings and their lengths.  NULL is stored if
-        the sequence is empty. ber_bvecfree() can be called to free the
-        allocated memory.  The tag of the sequence and of the octet
-        strings are ignored.
-
-'x'     Skip element.  The next element is skipped.  No argument is
-        required.
-
-'{'     Begin sequence.  No argument is required.  The initial sequence
-        tag and length are skipped.
-
-'}'     End sequence.  No argument is required.
-
-'['     Begin set.  No argument is required.  The initial set tag and
-        length are skipped.
-
-']'     End set.  No argument is required.
-
-           unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr);
-
-ber_peek_tag() returns the tag of the next element to be parsed in the
-BerElement argument.  The length of this element is stored in the
-*lenPtr argument.  LBER_DEFAULT is returned if there is no further data
-to be read.  The ber argument is not modified.
-
-           unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr);
-
-ber_skip_tag() is similar to ber_peek_tag(), except that the state
-pointer in the BerElement argument is advanced past the first tag and
-length, and is pointed to the value part of the next element.  This rou-
-tine should only be used with constructed types and situations when a
-BER encoding is used as the value of an OCTET STRING.  The length of the
-value is stored in *lenPtr.
-
-
-
-
-Expires: January 1998                                          [Page 45]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           unsigned long ber_first_element(BerElement *ber,
-                   unsigned long *lenPtr, char **opaquePtr);
-
-           unsigned long ber_next_element  (BerElement *ber,
-                   unsigned long *lenPtr, char *opaque);
-
-ber_first_element() and ber_next_element() are used to traverse a SET,
-SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
-ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
-and calls ber_peek_tag() for the first element inside the constructed
-value. LBER_DEFAULT is returned if the constructed value is empty.
-ber_next_element() positions the state at the start of the next element
-in the constructed type.  LBER_DEFAULT is returned if there are no
-further values.
-
-The len and opaque values should not be used by applications other than
-as arguments to ber_next_element(), as shown in the example below.
-
-
-13.5.  Decoding Example
-
-The following is an example of decoding an ASN.1 data type:
-
-      Example2Request ::= SEQUENCE {
-           dn    OCTET STRING, -- must be printable
-           scope ENUMERATED { b (0), s (1), w (2) },
-           ali   ENUMERATED { n (0), s (1), f (2), a (3) },
-           size  INTEGER,
-           time  INTEGER,
-           tonly BOOLEAN,
-           attrs SEQUENCE OF OCTET STRING, -- must be printable
-           [0] SEQUENCE OF SEQUENCE {
-              type  OCTET STRING -- must be printable,
-              crit  BOOLEAN DEFAULT FALSE,
-              value OCTET STRING
-           } OPTIONAL }
-
-      #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */
-
-      int decode_example2(struct berval *bv)
-      {
-           BerElement *ber;
-           unsigned long len;
-           int scope, ali, size, time, tonly;
-           char *dn = NULL, **attrs = NULL;
-           int res,i,rc = 0;
-
-           ber = ber_init(bv);
-
-
-
-Expires: January 1998                                          [Page 46]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-           if (ber == NULL) {
-                   printf("ERROR ber_init failed0);
-                   return -1;
-           }
-
-           res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali,
-                           &size,&time,&tonly,&attrs);
-
-           if (res == -1) {
-                   printf("ERROR ber_scanf failed0);
-                   ber_free(ber,1);
-                   return -1;
-           }
-
-           /* *** use dn */
-           ldap_memfree(dn);
-
-           for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
-                   /* *** use attrs[i] */
-                   ldap_memfree(attrs[i]);
-           }
-           ldap_memfree(attrs);
-
-           if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) {
-                   char *opaque;
-                   unsigned long tag;
-
-                   for (tag = ber_first_element(ber,&len,&opaque);
-                        tag != LBER_DEFAULT;
-                        tag = ber_next_element (ber,&len,opaque)) {
-
-                           unsigned long ttag, tlen;
-                           char *type;
-                           int crit;
-                           struct berval *value;
-
-                           if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
-                                   printf("ERROR cannot parse type0);
-                                   break;
-                           }
-                           /* *** use type */
-                           ldap_memfree(type);
-
-                           ttag = ber_peek_tag(ber,&tlen);
-                           if (ttag == 0x01) {  /* boolean */
-                                   if (ber_scanf(ber,"b",
-                                                 &crit) == LBER_ERROR) {
-                                           printf("ERROR cannot parse crit0);
-
-
-
-Expires: January 1998                                          [Page 47]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-                                           rc = -1;
-                                           break;
-                                   }
-                           } else if (ttag == 0x04) { /* octet string */
-                                   crit = 0;
-                           } else {
-                                   printf("ERROR extra field in controls0);
-                                   break;
-                           }
-
-                           if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
-                                   printf("ERROR cannot parse value0);
-                                   rc = -1;
-                                   break;
-                           }
-                           /* *** use value */
-                           ldap_bvfree(value);
-                   }
-           }
-
-           ber_scanf(ber,"}");
-
-           ber_free(ber,1);
-
-           return rc;
-       }
-
-
-
-14.  Security Considerations
-
-LDAPv2 supports security through protocol-level authentication using
-clear-text passwords.  LDAPv3 adds support for SASL [8] (Simple Authen-
-tication Security Layer) methods.  LDAPv3 also supports operation over a
-secure transport layer using Transport Layer Security TLS [8].  Readers
-are referred to the protocol documents for discussion of related secu-
-rity considerations.
-
-Implementations of this API should be cautious when handling authentica-
-tion credentials.  In particular, keeping long-lived copies of creden-
-tials without the application's knowledge is discouraged.
-
-
-15.  Acknowledgements
-
-Many members of the IETF ASID working group as well as members of the
-Internet at large have provided useful comments and suggestions that
-have been incorporated into this revision.
-
-
-
-Expires: January 1998                                          [Page 48]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-This original material upon which this revision is based was based upon
-work supported by the National Science Foundation under Grant No.  NCR-
-9416667.
-
-
-16.  Bibliography
-
-[1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
-     X.520.
-
-[2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
-     "Lightweight Directory Access Protocol Attribute Syntax Defini-
-     tions", INTERNET-DRAFT <draft-ietf-asid-ldapv3-attributes-06.txt>,
-     11 July 1997.
-
-[3]  T. Howes, "A String Representation of LDAP Search Filters,"
-     INTERNET-DRAFT <draft-ietf-asid-ldapv3-filter-02.txt>, May 1997.
-
-[4]  S. Kille, M. Wahl, "A UTF-8 String Representation of Distinguished
-     Names", INTERNET-DRAFT <draft-ietf-asid-ldapv3-dn-03.txt>, 29 April
-     1997.
-
-[5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
-     ing," RFC 1781, March 1995.
-
-[6]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
-     (v3)", INTERNET-DRAFT <draft-ietf-asid-ldapv3-protocol-06.txt>, 11
-     July 1997.
-
-[7]  A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server
-     Side Sorting of Search Result," INTERNET-DRAFT <draft-ietf-asid-
-     ldapv3-sorting-00.txt>, 16 April 1997.
-
-[8]  J. Meyers, "Simple Authentication and Security Layer", INTERNET-
-     DRAFT <draft-myers-auth-sasl-11.txt>, April 1997.
-
-[9]  "Lightweight Directory Access Protocol (v3) Extension for Transport
-     Layer Security", INTERNET-DRAFT <draft-ietf-asid-ldapv3-tls-
-     01.txt>, June 1997.
-
-[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
-     2044, October 1996.
-
-[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.
-
-
-
-
-
-
-
-Expires: January 1998                                          [Page 49]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-17.  Author's Addresses
-
-   Tim Howes
-   Netscape Communications Corp.
-   501 E. Middlefield Rd., Mailstop MV068
-   Mountain View, CA 94043
-   USA
-   +1 415 937-3419
-   howes@netscape.com
-
-
-   Mark Smith
-   Netscape Communications Corp.
-   501 E. Middlefield Rd., Mailstop MV068
-   Mountain View, CA 94043
-   USA
-   +1 415 937-3477
-   mcs@netscape.com
-
-   Andy Herron
-   Microsoft Corp.
-   1 Microsoft Way
-   Redmond, WA 98052
-   USA
-   +1 425 882-8080
-   andyhe@microsoft.com
-
-   Chris Weider
-   Microsoft Corp.
-   1 Microsoft Way
-   Redmond, WA 98052
-   USA
-   +1 425 882-8080
-   cweider@microsoft.com
-
-   Mark Wahl
-   Critical Angle Inc.
-   4815 W Braker Lane #502-385
-   Austin, TX 78759
-   USA
-   M.Wahl@critical-angle.com
-
-
-18.  Appendix A - Sample LDAP API Code
-
-   #include <ldap.h>
-
-   main()
-
-
-
-Expires: January 1998                                          [Page 50]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-   {
-           LDAP            *ld;
-           LDAPMessage     *res, *e;
-           int             i;
-           char            *a, *dn;
-           BerElement      *ptr;
-           char            **vals;
-
-           /* open an LDAP session */
-           if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
-                   exit( 1 );
-
-           /* authenticate as nobody */
-           if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
-                   ldap_perror( ld, "ldap_simple_bind_s" );
-                   exit( 1 );
-           }
-
-           /* search for entries with cn of "Babs Jensen", return all attrs  */
-           if ( ldap_search_s( ld, "o=University of Michigan, c=US",
-               LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
-               != LDAP_SUCCESS ) {
-                   ldap_perror( ld, "ldap_search_s" );
-                   exit( 1 );
-           }
-
-           /* step through each entry returned */
-           for ( e = ldap_first_entry( ld, res ); e != NULL;
-               e = ldap_next_entry( ld, e ) ) {
-                   /* print its name */
-                   dn = ldap_get_dn( ld, e );
-                   printf( "dn: %s\n", dn );
-                   ldap_memfree( dn );
-
-                   /* print each attribute */
-                   for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
-                       a = ldap_next_attribute( ld, e, ptr ) ) {
-                           printf( "attribute: %s\n", a );
-
-                           /* print each value */
-                           vals = ldap_get_values( ld, e, a );
-                           for ( i = 0; vals[i] != NULL; i++ ) {
-                                   printf( "value: %s\n", vals[i] );
-                           }
-                           ldap_value_free( vals );
-                   }
-                   if ( ptr != NULL ) {
-                           ldap_ber_free( ptr, 0 );
-
-
-
-Expires: January 1998                                          [Page 51]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-                   }
-           }
-           /* free the search results */
-           ldap_msgfree( res );
-
-           /* close and free connection resources */
-           ldap_unbind( ld );
-   }
-
-
-
-19.  Appendix B - Outstanding Issues
-
-
-19.1.  Support for multithreaded applications
-
-In order to support multithreaded applications in a platform-independent
-way, some additions to the LDAP API are needed.  Different implementors
-have taken different paths to solve this problem in the past.  A common
-set of thread-related API calls must be defined so that application
-developers are not unduly burdened.  These will be added to a future
-revision of this specification.
-
-
-19.2.  Using Transport Layer Security (TLS)
-
-The API calls used to support TLS must be specified.  They will be added
-to a future revision of this specification.
-
-
-19.3.  Client control for chasing referrals
-
-A client control has been defined that can be used to specify on a per-
-operation basis whether references and external referrals are automati-
-cally chased by the client library.  This will be added to a future
-revision of this specification.
-
-
-19.4.  Potential confusion between hostname:port and IPv6 addresses
-
-String representations of IPv6 network addresses [11] can contain colon
-characters.  The ldap_init() call is specified to take strings of the
-form "hostname:port" or "ipaddress:port".  If IPv6 addresses are used,
-the latter could be ambiguous.  A future revision of this specification
-will resolve this issue.
-
-
-
-
-
-
-Expires: January 1998                                          [Page 52]
-
-C LDAP API      The C LDAP Application Program Interface    29 July 1997
-
-
-19.5.  Need to track SASL API standardization efforts
-
-If a standard Simple Authentication and Security Layer API is defined,
-it may be necessary to modify the LDAP API to accommodate it.
-
-
-19.6.  Support for character sets other than UTF-8?
-
-Some application developers would prefer to pass string data using a
-character set other than UTF-8.  This could be accommodated by adding a
-new option to ldap_set_option() that supports choosing a character set.
-If this feature is added, the number of different character sets sup-
-ported should definitely be minimized.
-
-
-19.7.  Use of UTF-8 with LDAPv2 servers
-
-Strings are always passed as UTF-8 in this API but LDAP version 2
-servers do not support the full range of UTF-8 characters.  The expected
-behavior of this API when using LDAP version 2 with unsupported charac-
-ters should be specified.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Expires: January 1998                                          [Page 53]
-
-
-
-1.     Status of this Memo............................................1
-2.     Introduction...................................................1
-3.     Overview of the LDAP Model.....................................2
-4.     Overview of LDAP API Use.......................................3
-5.     Common Data Structures.........................................4
-6.     LDAP Error Codes...............................................5
-7.     Performing LDAP Operations.....................................6
-7.1.      Initializing an LDAP Session................................6
-7.2.      LDAP Session Handle Options.................................7
-7.3.      Working with controls.......................................10
-7.4.      Authenticating to the directory.............................11
-7.5.      Closing the session.........................................13
-7.6.      Searching...................................................13
-7.7.      Reading an Entry............................................17
-7.8.      Listing the Children of an Entry............................17
-7.9.      Comparing a Value Against an Entry..........................17
-7.10.     Modifying an entry..........................................19
-7.11.     Modifying the Name of an Entry..............................21
-7.12.     Adding an entry.............................................23
-7.13.     Deleting an entry...........................................25
-7.14.     Extended Operations.........................................26
-8.     Abandoning An Operation........................................28
-9.     Obtaining Results and Peeking Inside LDAP Messages.............29
-10.    Handling Errors and Parsing Results............................31
-11.    Stepping Through a List of Results.............................33
-12.    Parsing Search Results.........................................34
-12.1.     Stepping Through a List of Entries..........................34
-12.2.     Stepping Through the Attributes of an Entry.................35
-12.3.     Retrieving the Values of an Attribute.......................36
-12.4.     Retrieving the name of an entry.............................37
-13.    Encoded ASN.1 Value Manipulation...............................39
-13.1.     General.....................................................39
-13.2.     Encoding....................................................40
-13.3.     Encoding Example............................................42
-13.4.     Decoding....................................................43
-13.5.     Decoding Example............................................46
-14.    Security Considerations........................................48
-15.    Acknowledgements...............................................48
-16.    Bibliography...................................................49
-17.    Author's Addresses.............................................50
-18.    Appendix A - Sample LDAP API Code..............................50
-19.    Appendix B - Outstanding Issues................................52
-19.1.     Support for multithreaded applications......................52
-19.2.     Using Transport Layer Security (TLS)........................52
-19.3.     Client control for chasing referrals........................52
-19.4.     Potential confusion between hostname:port and IPv6 addresses52
-19.5.     Need to track SASL API standardization efforts..............53
-19.6.     Support for character sets other than UTF-8?................53
-19.7.     Use of UTF-8 with LDAPv2 servers............................53
-
-
-
-
-
-
-
-