7 Network Working Group M. Smith, Editor
8 INTERNET-DRAFT Netscape Communications Corp.
9 Intended Category: Standards Track T. Howes
10 Obsoletes: RFC 1823 Netscape Communications Corp.
11 Expires: 23 August 1999 A. Herron
14 Innosoft International, Inc.
21 The C LDAP Application Program Interface
22 <draft-ietf-ldapext-ldap-c-api-02.txt>
25 1. Status of this Memo
27 This document is an Internet-Draft and is in full conformance with all
28 provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
29 ments of the Internet Engineering Task Force (IETF), its areas, and its
30 working groups. Note that other groups may also distribute working
31 documents as Internet-Drafts.
33 Internet-Drafts are draft documents valid for a maximum of six months
34 and may be updated, replaced, or obsoleted by other documents at any
35 time. It is inappropriate to use Internet-Drafts as reference material
36 or to cite them other than as "work in progress."
38 The list of current Internet-Drafts can be accessed at
39 http://www.ietf.org/ietf/1id-abstracts.txt.
41 The list of Internet-Draft Shadow Directories can be accessed at
42 http://www.ietf.org/shadow.html.
44 This draft document will be submitted to the RFC Editor as a Standards
45 Track document. Distribution of this memo is unlimited. Technical dis-
46 cussion of this document will take place on the IETF LDAP Extension
47 Working Group mailing list <ietf-ldapext@netscape.com>. Please send
48 editorial comments directly to the authors.
50 Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
52 Please see the Copyright section near the end of this document for more
58 Expires: 23 August 1999 [Page 1]
60 C LDAP API C LDAP Application Program Interface 23 February 1999
65 This document defines a C language application program interface (API)
66 to the Lightweight Directory Access Protocol (LDAP). This document
67 replaces the previous definition of this API, defined in RFC 1823,
68 updating it to include support for features found in version 3 of the
69 LDAP protocol. New extended operation functions were added to support
70 LDAPv3 features such as controls. In addition, other LDAP API changes
71 were made to support information hiding and thread safety.
73 The C LDAP API is designed to be powerful, yet simple to use. It defines
74 compatible synchronous and asynchronous interfaces to LDAP to suit a
75 wide variety of applications. This document gives a brief overview of
76 the LDAP model, then an overview of how the API is used by an applica-
77 tion program to obtain LDAP information. The API calls are described in
78 detail, followed by appendices that provide example code demonstrating
79 use of the API, the namespace consumed by the API, a summary of require-
80 ments for API extensions, known incompatibilities with RFC 1823, and a
81 list of changes made since the last revision of this document.
86 1. Status of this Memo............................................1
87 2. Introduction...................................................2
88 3. Table of Contents..............................................2
89 4. Overview of the LDAP Model.....................................4
90 5. Overview of LDAP API Use.......................................4
91 6. Header File Requirements.......................................6
92 7. Common Data Structures.........................................7
93 8. Retrieving Information About the API Implementation............8
94 8.1. Retrieving Information at Compile Time......................8
95 8.2. Retrieving Information During Execution.....................10
96 9. LDAP Error Codes...............................................13
97 10. Performing LDAP Operations.....................................14
98 10.1. Initializing an LDAP Session................................14
99 10.2. LDAP Session Handle Options.................................15
100 10.3. Working With Controls.......................................21
101 10.3.1. A Client Control That Governs Referral Processing........22
102 10.4. Authenticating to the directory.............................22
103 10.5. Closing the session.........................................25
104 10.6. Searching...................................................26
105 10.7. Reading an Entry............................................30
106 10.8. Listing the Children of an Entry............................30
107 10.9. Comparing a Value Against an Entry..........................30
108 10.10. Modifying an entry..........................................32
109 10.11. Modifying the Name of an Entry..............................34
110 10.12. Adding an entry.............................................36
114 Expires: 23 August 1999 [Page 2]
116 C LDAP API C LDAP Application Program Interface 23 February 1999
119 10.13. Deleting an entry...........................................38
120 10.14. Extended Operations.........................................40
121 11. Abandoning An Operation........................................41
122 12. Obtaining Results and Peeking Inside LDAP Messages.............42
123 13. Handling Errors and Parsing Results............................44
124 14. Stepping Through a List of Results.............................47
125 15. Parsing Search Results.........................................48
126 15.1. Stepping Through a List of Entries or References............48
127 15.2. Stepping Through the Attributes of an Entry.................49
128 15.3. Retrieving the Values of an Attribute.......................50
129 15.4. Retrieving the name of an entry.............................51
130 15.5. Retrieving controls from an entry...........................52
131 15.6. Parsing References..........................................53
132 16. Encoded ASN.1 Value Manipulation...............................54
133 16.1. General.....................................................54
134 16.2. Encoding....................................................55
135 16.3. Encoding Example............................................58
136 16.4. Decoding....................................................59
137 16.5. Decoding Example............................................61
138 17. Security Considerations........................................64
139 18. Acknowledgements...............................................64
140 19. Copyright......................................................64
141 20. Bibliography...................................................65
142 21. Authors' Addresses.............................................66
143 22. Appendix A - Sample C LDAP API Code............................67
144 23. Appendix B - Namespace Consumed By This Specification..........68
145 24. Appendix C - Summary of Requirements for API Extensions........69
146 24.1. Compatibility...............................................69
147 24.2. Style.......................................................69
148 24.3. Dependence on Externally Defined Types......................69
149 24.4. Compile Time Information....................................69
150 24.5. Runtime Information.........................................70
151 24.6. Values Used for Session Handle Options......................70
152 25. Appendix D - Known Incompatibilities with RFC 1823.............70
153 25.1. Opaque LDAP Structure.......................................70
154 25.2. Additional Error Codes......................................70
155 25.3. Freeing of String Data with ldap_memfree()..................71
156 25.4. Changes to ldap_result()....................................71
157 25.5. Changes to ldap_first_attribute() and ldap_next_attribute...71
158 25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......71
159 25.7. API Specification Clarified.................................72
160 25.8. Deprecated Functions........................................72
161 26. Appendix E - Changes Made Since Last Document Revision.........72
162 26.1. API Changes.................................................73
163 26.2. Editorial changes...........................................74
170 Expires: 23 August 1999 [Page 3]
172 C LDAP API C LDAP Application Program Interface 23 February 1999
175 4. Overview of the LDAP Model
177 LDAP is the lightweight directory access protocol, described in [2] and
178 [6]. It can provide a lightweight frontend to the X.500 directory [1],
179 or a stand-alone service. In either mode, LDAP is based on a client-
180 server model in which a client makes a TCP connection to an LDAP server,
181 over which it sends requests and receives responses.
183 The LDAP information model is based on the entry, which contains infor-
184 mation about some object (e.g., a person). Entries are composed of
185 attributes, which have a type and one or more values. Each attribute has
186 a syntax that determines what kinds of values are allowed in the attri-
187 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
188 values behave during directory operations (e.g., is case significant
191 Entries may be organized in a tree structure, usually based on politi-
192 cal, geographical, and organizational boundaries. Each entry is uniquely
193 named relative to its sibling entries by its relative distinguished name
194 (RDN) consisting of one or more distinguished attribute values from the
195 entry. At most one value from each attribute may be used in the RDN.
196 For example, the entry for the person Babs Jensen might be named with
197 the "Barbara Jensen" value from the commonName attribute.
199 A globally unique name for an entry, called a distinguished name or DN,
200 is constructed by concatenating the sequence of RDNs from the entry up
201 to the root of the tree. For example, if Babs worked for the University
202 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
203 o=University of Michigan, c=US". The DN format used by LDAP is defined
206 Operations are provided to authenticate, search for and retrieve infor-
207 mation, modify information, and add and delete entries from the tree.
208 The next sections give an overview of how the API is used and detailed
209 descriptions of the LDAP API calls that implement all of these func-
213 5. Overview of LDAP API Use
215 An application generally uses the C LDAP API in four simple steps.
217 1. Initialize an LDAP session with a primary LDAP server. The
218 ldap_init() function returns a handle to the session, allowing
219 multiple connections to be open at once.
221 2. Authenticate to the LDAP server. The ldap_sasl_bind() function
222 and friends support a variety of authentication methods.
226 Expires: 23 August 1999 [Page 4]
228 C LDAP API C LDAP Application Program Interface 23 February 1999
231 3. Perform some LDAP operations and obtain some results.
232 ldap_search() and friends return results which can be parsed by
233 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
235 4. Close the session. The ldap_unbind() function closes the connec-
238 Operations can be performed either synchronously or asynchronously. The
239 names of the synchronous functions end in _s. For example, a synchronous
240 search can be completed by calling ldap_search_s(). An asynchronous
241 search can be initiated by calling ldap_search(). All synchronous rou-
242 tines return an indication of the outcome of the operation (e.g, the
243 constant LDAP_SUCCESS or some other error code). The asynchronous rou-
244 tines make available to the caller the message id of the operation ini-
245 tiated. This id can be used in subsequent calls to ldap_result() to
246 obtain the result(s) of the operation. An asynchronous operation can be
247 abandoned by calling ldap_abandon() or ldap_abandon_ext().
249 Results and errors are returned in an opaque structure called LDAPMes-
250 sage. Routines are provided to parse this structure, step through
251 entries and attributes returned, etc. Routines are also provided to
252 interpret errors. Later sections of this document describe these rou-
253 tines in more detail.
255 LDAP version 3 servers may return referrals and references to other
256 servers. By default, implementations of this API will attempt to follow
257 referrals automatically for the application. This behavior can be dis-
258 abled globally (using the ldap_set_option() call) or on a per-request
259 basis through the use of a client control.
261 All DN and string attribute values passed into or produced by this C
262 LDAP API are represented using the character set of the underlying LDAP
263 protocol version in use. When this API is used with LDAPv3, DN and
264 string values are represented as UTF-8[10] characters. When this API is
265 used with LDAPv2, the US-ASCII[12] or T.61[12] character set are used.
266 Future documents may specific additional APIs supporting other character
269 For compatibility with existing applications, implementations of this
270 API will by default use version 2 of the LDAP protocol. Applications
271 that intend to take advantage of LDAP version 3 features will need to
272 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
275 Note that this API is designed for use in environments where the 'int'
276 type is at least 32 bits in size.
282 Expires: 23 August 1999 [Page 5]
284 C LDAP API C LDAP Application Program Interface 23 February 1999
287 6. Header File Requirements
289 To promote portability of applications, implementations of this C LDAP
290 API must conform to the following requirements of the header files used
291 by applications to access the services of this API:
294 Applications are only required to include a single header file
295 named ldap.h to access all of the API services described in this
296 document. Therefore, the following C source program must com-
307 Note that it is permissible for the ldap.h header file to
308 include other implementation-specific header files.
310 Implementations SHOULD also provide a header file named lber.h to faci-
311 late development of applications desiring compatibility with older LDAP
312 implementations. The lber.h header file may be empty.
316 All header files should be idempotent; that is, if they are
317 included more than once the effect is as if they had only been
320 Must Be Included Before API Is Used
321 An application must include the ldap.h header file before
322 referencing any of the function or type definitions described in
323 this API specification.
326 If possible, header files should be mutually independent with
327 minimal dependence on system or any other header files.
329 Use of the 'const' Keyword
330 This API specification is defined in terms of ISO C[13]. It
331 makes use of function prototypes and the 'const' keyword. The
332 use of 'const' in this specification is limited to simple, non-
333 array function parameters to avoid forcing applications to
334 declare parameters and variables that accept return values from
338 Expires: 23 August 1999 [Page 6]
340 C LDAP API C LDAP Application Program Interface 23 February 1999
343 LDAP API functions as 'const.' Implementations specifically
344 designed to be used with non-ISO C translators may provide func-
345 tion declarations without prototypes or function prototypes
346 without specification of 'const' arguments.
348 Definition of 'struct timeval'
349 This API specification uses the 'struct timeval' type. Imple-
350 mentations of this API should ensure that the struct timeval
351 type is by default defined as a consequence of including the
352 ldap.h header file. Because struct timeval is usually defined
353 in one or more system header files, it is possible for header
354 file conflicts to occur if ldap.h also defines it or arranges
355 for it to be defined by including another header file. There-
356 fore, applications may want to arrange for struct timeval to be
357 defined before they include ldap.h. To support this, the ldap.h
358 header file must not itself define struct timeval if the prepro-
359 cessor symbol LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h
363 7. Common Data Structures
365 Some data structures that are common to several LDAP API functions are
368 typedef struct ldap LDAP;
370 typedef struct ldapmsg LDAPMessage;
372 typedef struct berelement BerElement;
375 unsigned long bv_len;
384 The LDAP structure is an opaque data type that represents an LDAP ses-
385 sion Typically this corresponds to a connection to a single server, but
386 it may encompass several server connections in the face of LDAPv3 refer-
389 The LDAPMessage structure is an opaque data type that is used to return
390 entry, reference, result, and error information. An LDAPMessage
394 Expires: 23 August 1999 [Page 7]
396 C LDAP API C LDAP Application Program Interface 23 February 1999
399 structure may represent the beginning of a list, or chain of messages
400 that consists of a series of entries, references, and result messages as
401 returned by LDAP operations such as search. LDAP API functions such as
402 ldap_parse_result() that operate on message chains that may contain more
403 than one result message always operate on the first result message in
404 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
405 section of this document for more information.
407 The BerElement structure is an opaque data type that is used to hold
408 data and state information about encoded data. It is described in more
409 detail in the section "Encoded ASN.1 Value Manipulation" later in this
412 The berval structure is used to represent arbitrary binary data and its
413 fields have the following meanings:
415 bv_len Length of data in bytes.
417 bv_val A pointer to the data itself.
420 The timeval structure is used to represent an interval of time and its
421 fields have the following meanings:
423 tv_sec Seconds component of time interval.
425 tv_usec Microseconds component of time interval.
427 See the earlier section "Header File Requirements" for more information
431 8. Retrieving Information About the API Implementation
433 Applications developed to this specification need to be able to deter-
434 mine information about the particular API implementation they are using
435 both at compile time and during execution.
438 8.1. Retrieving Information at Compile Time
440 All conformant implementations MUST include the following five defini-
441 tions in a header file so compile time tests can be done by LDAP
444 #define LDAP_API_VERSION level
445 #define LDAP_VERSION_MIN min-version
446 #define LDAP_VERSION_MAX max-version
450 Expires: 23 August 1999 [Page 8]
452 C LDAP API C LDAP Application Program Interface 23 February 1999
455 #define LDAP_VENDOR_NAME "vend-name"
456 #define LDAP_VENDOR_VERSION vend-version
460 "level" is replaced with the RFC number given to this C LDAP API
461 specification when it is published as a standards track RFC.
463 min-version is replaced with the lowest LDAP protocol version sup-
464 ported by the implementation.
466 max-version is replaced with the highest LDAP protocol version sup-
467 ported by the implementation. This should be 3.
469 "vend-name" is replaced with a text string that identifies the
470 party that supplies the API implementation.
472 "vend-version" is a supplier-specific version number multiplied
475 Note that the LDAP_VENDOR_NAME macro may be defined as "" if no vendor
476 name is available and the LDAP_VENDOR_VERSION macro may be defined as 0
477 if no vendor-specific version information is available.
479 For example, if this specification is published as RFC 88888, Netscape
480 Communication's version 4.0 implementation that supports LDAPv2 and v3
481 might include macro definitions like these:
483 #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */
484 #define LDAP_VERSION_MIN 2
485 #define LDAP_VERSION_MAX 3
486 #define LDAP_VENDOR_NAME "Netscape Communications Corp."
487 #define LDAP_VENDOR_VERSION 400 /* version 4.0 */
489 and application code can test the C LDAP API version level using a
490 construct such as this one:
492 #if (LDAP_API_VERSION >= 88888)
493 /* use features supported in RFC 88888 or later */
496 Until such time as this document is published as an RFC, implementations
497 should use the value 2000 plus the revision number of this draft for
498 LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
499 for revision 03 of this draft is 2003.
501 Documents that extend this specification SHOULD define a macro of the
506 Expires: 23 August 1999 [Page 9]
508 C LDAP API C LDAP Application Program Interface 23 February 1999
511 #define LDAP_API_FEATURE_x level
513 where "x" is replaced with a name (textual identifier) for the feature
514 and "level" is replaced with the number of the RFC that specifies the
515 API extension. The name SHOULD NOT begin with the string "X_".
517 For example, if C LDAP API extensions for Transport Layer Security [9]
518 were published in RFC 99999, that RFC might require conformant implemen-
519 tations to define a macro like this:
521 #define LDAP_API_FEATURE_TLS 99999
524 Private or experimental API extensions may be indicated by defining a
525 macro of this same form where "x" (the extension's name) begins with the
526 string "X_" and "level" is replaced with a integer number that is
527 specific to the extension.
530 8.2. Retrieving Information During Execution
532 The ldap_get_option() call (described in greater detail later in this
533 document) can be used during execution in conjunction with an option
534 parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic
535 information about the API and about the specific implementation being
536 used. The ld parameter to ldap_get_option() can be either NULL or a
537 valid LDAP session handle which was obtained by calling ldap_init().
538 The optdata parameter to ldap_get_option() MUST be the address of an
539 LDAPAPIInfo structure which is defined as follows:
541 typedef struct ldapapiinfo {
542 int ldapai_info_version; /* version of this struct (1) */
543 int ldapai_api_version; /* revision of API supported */
544 int ldapai_protocol_version; /* highest LDAP version supported */
545 char **ldapai_extensions; /* names of API extensions */
546 char *ldapai_vendor_name; /* name of supplier */
547 int ldapai_vendor_version; /* supplier-specific version times 100 */
550 In addition, API implementations MUST include the following macro defin-
553 #define LDAP_API_INFO_VERSION 1
555 Note that the ldapai_info_version field of the LDAPAPIInfo structure
556 should be set to the value LDAP_API_INFO_VERSION (1) before calling
557 ldap_get_option() so that it can be checked for consistency. All other
558 fields are set by the ldap_get_option() function.
562 Expires: 23 August 1999 [Page 10]
564 C LDAP API C LDAP Application Program Interface 23 February 1999
567 The members of the LDAPAPIInfo structure are:
570 A number that identifies the version of the LDAPAPIInfo struc-
571 ture. This should be set to the value LDAP_API_INFO_VERSION
572 (1) before calling ldap_get_option(). If the value received
573 is not recognized by the API implementation, the
574 ldap_get_option() function sets ldapai_info_version to a valid
575 value that would be recognized, sets the ldapai_api_version to
576 the correct value, and returns an error without filling in any
577 of the other fields in the LDAPAPIInfo structure.
580 A number that matches that assigned to the C LDAP API RFC sup-
581 ported by the API implementation. This should match the value
582 of the LDAP_API_VERSION macro defined earlier.
584 ldapai_protocol_version
585 The highest LDAP protocol version supported by the implementa-
586 tion. For example, if LDAPv3 is the highest version supported
587 then this field will be set to 3.
590 A NULL-terminated array of character strings that lists the
591 names of the API extensions supported by the LDAP API imple-
592 mentation. These names will typically match the textual iden-
593 tifiers that appear in the "x" portion of the
594 LDAP_API_FEATURE_x macros described above, although the pre-
595 cise value MUST be defined by documents that specify C LDAP
596 API extensions. If no API extensions are supported, this
597 field will be set to NULL. The caller is responsible for
598 disposing of the memory occupied by this array by passing it
599 to ldap_value_free() which is described later in this docu-
600 ment. To retrieve more information about a particular exten-
601 sion, the ldap_get_option() call can be used with an option
602 parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
603 data parameter to the ldap_get_option() MUST be the address of
604 an LDAPAPIFeatureInfo structure which is defined as follows:
606 typedef struct ldap_apifeature_info {
607 int ldapaif_info_version; /* version of this struct (1) */
608 char *ldapaif_name; /* name of supported feature */
609 int ldapaif_version; /* revision of supported feature */
610 } LDAPAPIFeatureInfo;
612 In addition, API implementations MUST include the following
618 Expires: 23 August 1999 [Page 11]
620 C LDAP API C LDAP Application Program Interface 23 February 1999
623 #define LDAP_FEATURE_INFO_VERSION 1
625 Note that the ldapaif_info_version field of the LDAPAPI-
626 FeatureInfo structure should be set to the value
627 LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
628 should be set to the extension name string as described below
629 before ldap_get_option() is called. The call will fill in the
630 ldapaif_version field of the LDAPAPIFeatureInfo structure.
632 The members of the LDAPAPIFeatureInfo structure are:
635 A number that identifies the version of the LDAPAPI-
636 FeatureInfo structure. This should be set to the value
637 LDAP_FEATURE_INFO_VERSION (1) before calling
638 ldap_get_option(). If the value received is not recognized
639 by the API implementation, the ldap_get_option() function
640 sets ldapaif_info_version to a valid value that would be
641 recognized and returns an error without filling in the
642 ldapaif_version field in the LDAPAPIFeatureInfo structure.
645 The name of an extension, as returned in the
646 ldapai_extensions array of the LDAPAPIInfo structure and as
647 specified in the document that describes the extension.
650 This field will be set as a result of calling
651 ldap_get_option(). It is a number that matches that
652 assigned to the C LDAP API extension RFC supported for this
653 extension. For private or experimental API extensions, the
654 value is extension-specific. In either case, the value of
655 ldapaxi_ext_version should be identical to the value of the
656 LDAP_API_FEATURE_x macro defined for the extension
660 A zero-terminated string that contains the name of the party
661 that produced the LDAP API implementation. This field may be
662 set to NULL if no name is available. If non-NULL, the caller
663 is responsible for disposing of the memory occupied by passing
664 this pointer to ldap_memfree() which is described later in
665 this document. This value SHOULD match the value of the
666 LDAP_VENDOR_NAME macro described earlier in this document.
668 ldapai_vendor_version
669 An implementation-specific version number multiplied by 100.
670 For example, if the implementation version is 4.0 then this
674 Expires: 23 August 1999 [Page 12]
676 C LDAP API C LDAP Application Program Interface 23 February 1999
679 field will be set to 400. If no version information is avail-
680 able, this field will be set to 0. This value SHOULD match
681 the value of the LDAP_VENDOR_VERSION macro described earlier
687 Many of the LDAP API routines return LDAP error codes, some of which
688 indicate local errors and some of which may be returned by servers. All
689 of the LDAP error codes returned will be positive integers. Supported
690 error codes are (hexadecimal values are given in parentheses after the
694 LDAP_OPERATIONS_ERROR (0x01)
695 LDAP_PROTOCOL_ERROR (0x02)
696 LDAP_TIMELIMIT_EXCEEDED (0x03)
697 LDAP_SIZELIMIT_EXCEEDED (0x04)
698 LDAP_COMPARE_FALSE (0x05)
699 LDAP_COMPARE_TRUE (0x06)
700 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
701 LDAP_STRONG_AUTH_REQUIRED (0x08)
702 LDAP_REFERRAL (0x0a) -- new in LDAPv3
703 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3
704 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
705 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
706 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
707 LDAP_NO_SUCH_ATTRIBUTE (0x10)
708 LDAP_UNDEFINED_TYPE (0x11)
709 LDAP_INAPPROPRIATE_MATCHING (0x12)
710 LDAP_CONSTRAINT_VIOLATION (0x13)
711 LDAP_TYPE_OR_VALUE_EXISTS (0x14)
712 LDAP_INVALID_SYNTAX (0x15)
713 LDAP_NO_SUCH_OBJECT (0x20)
714 LDAP_ALIAS_PROBLEM (0x21)
715 LDAP_INVALID_DN_SYNTAX (0x22)
716 LDAP_IS_LEAF (0x23) -- not used in LDAPv3
717 LDAP_ALIAS_DEREF_PROBLEM (0x24)
718 LDAP_INAPPROPRIATE_AUTH (0x30)
719 LDAP_INVALID_CREDENTIALS (0x31)
720 LDAP_INSUFFICIENT_ACCESS (0x32)
722 LDAP_UNAVAILABLE (0x34)
723 LDAP_UNWILLING_TO_PERFORM (0x35)
724 LDAP_LOOP_DETECT (0x36)
725 LDAP_NAMING_VIOLATION (0x40)
726 LDAP_OBJECT_CLASS_VIOLATION (0x41)
730 Expires: 23 August 1999 [Page 13]
732 C LDAP API C LDAP Application Program Interface 23 February 1999
735 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
736 LDAP_NOT_ALLOWED_ON_RDN (0x43)
737 LDAP_ALREADY_EXISTS (0x44)
738 LDAP_NO_OBJECT_CLASS_MODS (0x45)
739 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP
740 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3
742 LDAP_SERVER_DOWN (0x51)
743 LDAP_LOCAL_ERROR (0x52)
744 LDAP_ENCODING_ERROR (0x53)
745 LDAP_DECODING_ERROR (0x54)
747 LDAP_AUTH_UNKNOWN (0x56)
748 LDAP_FILTER_ERROR (0x57)
749 LDAP_USER_CANCELLED (0x58)
750 LDAP_PARAM_ERROR (0x59)
751 LDAP_NO_MEMORY (0x5a)
752 LDAP_CONNECT_ERROR (0x5b)
753 LDAP_NOT_SUPPORTED (0x5c)
754 LDAP_CONTROL_NOT_FOUND (0x5d)
755 LDAP_NO_RESULTS_RETURNED (0x5e)
756 LDAP_MORE_RESULTS_TO_RETURN (0x5f)
757 LDAP_CLIENT_LOOP (0x60)
758 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
761 10. Performing LDAP Operations
763 This section describes each LDAP operation API call in detail. All func-
764 tions take a "session handle," a pointer to an LDAP structure containing
765 per-connection information. Many routines return results in an LDAPMes-
766 sage structure. These structures and others are described as needed
770 10.1. Initializing an LDAP Session
772 ldap_init() initializes a session with an LDAP server. The server is not
773 actually contacted until an operation is performed that requires it,
774 allowing various options to be set after initialization.
777 const char *hostname,
781 Use of the following routine is deprecated:
786 Expires: 23 August 1999 [Page 14]
788 C LDAP API C LDAP Application Program Interface 23 February 1999
792 const char *hostname,
795 Unlike ldap_init(), ldap_open() attempts to make a server connection
796 before returning to the caller.
800 hostname Contains a space-separated list of hostnames or dotted strings
801 representing the IP address of hosts running an LDAP server to
802 connect to. Each hostname in the list can include an optional
803 port number which is separated from the host itself with a
804 colon (:) character. The hosts will be tried in the order
805 listed, stopping with the first one to which a successful con-
808 Note: A suitable representation for including a literal IPv6[11]
809 address in the hostname parameter is desired, but has not yet been
810 determined or implemented in practice.
812 portno Contains the TCP port number to connect to. The default LDAP
813 port of 389 can be obtained by supplying the constant
814 LDAP_PORT. If a host includes a port number then this parame-
817 ldap_init() and ldap_open() both return a "session handle," a pointer to
818 an opaque structure that should be passed to subsequent calls pertaining
819 to the session. These routines return NULL if the session cannot be ini-
820 tialized in which case the operating system error reporting mechanism
821 can be checked to see why the call failed.
823 Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
824 described below must be completed before other operations can be per-
825 formed on the session. LDAPv3 does not require that a bind operation be
826 completed before other operations can be performed.
828 The calling program can set various attributes of the session by calling
829 the routines described in the next section.
832 10.2. LDAP Session Handle Options
834 The LDAP session handle returned by ldap_init() is a pointer to an
835 opaque data type representing an LDAP session. In RFC 1823 this data
836 type was a structure exposed to the caller, and various fields in the
837 structure could be set to control aspects of the session, such as size
838 and time limits on searches.
842 Expires: 23 August 1999 [Page 15]
844 C LDAP API C LDAP Application Program Interface 23 February 1999
847 In the interest of insulating callers from inevitable changes to this
848 structure, these aspects of the session are now accessed through a pair
849 of accessor functions, described below.
851 ldap_get_option() is used to access the current value of various
852 session-wide parameters. ldap_set_option() is used to set the value of
853 these parameters. Note that some options are READ-ONLY and cannot be
854 set; it is an error to call ldap_set_option() and attempt to set a
857 Note that if automatic referral following is enabled (the default), any
858 connections created during the course of following referrals will
859 inherit the options associated with the session that sent the original
860 request that caused the referrals to be returned.
874 #define LDAP_OPT_ON ((void *)1)
875 #define LDAP_OPT_OFF ((void *)0)
880 ld The session handle. If this is NULL, a set of global defaults is
881 accessed. New LDAP session handles created with ldap_init() or
882 ldap_open() inherit their characteristics from these global
885 option The name of the option being accessed or set. This parameter
886 should be one of the following constants, which have the indi-
887 cated meanings. After the constant the actual hexadecimal value
888 of the constant is listed in parentheses.
891 LDAP_OPT_API_INFO (0x00)
892 Type for invalue parameter: not applicable (option is READ-ONLY)
894 Type for outvalue parameter: LDAPAPIInfo *
898 Expires: 23 August 1999 [Page 16]
900 C LDAP API C LDAP Application Program Interface 23 February 1999
904 Used to retrieve some basic information about the LDAP API
905 implementation at execution time. See the section "Retriev-
906 ing Information About the API Implementation" above for more
907 information. This option is READ-ONLY and cannot be set.
910 Type for invalue parameter: not applicable (option is READ-
913 Type for outvalue parameter: int *
916 The underlying socket descriptor corresponding to the pri-
917 mary LDAP connection. This option is READ-ONLY and cannot
920 LDAP_OPT_DEREF (0x02)
921 Type for invalue parameter: int *
923 Type for outvalue parameter: int *
926 Determines how aliases are handled during search. It can
927 have one of the following values: LDAP_DEREF_NEVER (0x00),
928 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
929 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
930 means aliases should be dereferenced during the search but
931 not when locating the base object of the search. The
932 LDAP_DEREF_FINDING value means aliases should be derefer-
933 enced when locating the base object but not during the
936 LDAP_OPT_SIZELIMIT (0x03)
937 Type for invalue parameter: int *
939 Type for outvalue parameter: int *
942 A limit on the number of entries to return from a search.
943 A value of LDAP_NO_LIMIT (0) means no limit.
945 LDAP_OPT_TIMELIMIT (0x04)
946 Type for invalue parameter: int *
948 Type for outvalue parameter: int *
954 Expires: 23 August 1999 [Page 17]
956 C LDAP API C LDAP Application Program Interface 23 February 1999
959 A limit on the number of seconds to spend on a search. A
960 value of LDAP_NO_LIMIT (0) means no limit. This value is
961 passed to the server in the search request only; it does
962 not affect how long the C LDAP API implementation itself
963 will wait locally for search results. The timeout parame-
964 ter passed to ldap_search_ext_s() or ldap_result() -- both
965 of which are described later in this document -- can be
966 used to specify both a local and server side time limit.
968 LDAP_OPT_REFERRALS (0x08)
969 Type for invalue parameter: void * (LDAP_OPT_ON or
972 Type for outvalue parameter: int *
975 Determines whether the LDAP library automatically follows
976 referrals returned by LDAP servers or not. It can be set
977 to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any
978 non-NULL pointer value passed to ldap_set_option() enables
979 this option. When reading the current setting using
980 ldap_get_option(), a zero value means off and any non-zero
983 LDAP_OPT_RESTART (0x09)
984 Type for invalue parameter: void * (LDAP_OPT_ON or
987 Type for outvalue parameter: int *
990 Determines whether LDAP I/O operations should automati-
991 cally be restarted if they abort prematurely. It should be
992 set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF;
993 any non-NULL pointer value passed to ldap_set_option()
994 enables this option. When reading the current setting
995 using ldap_get_option(), a zero value means off and any
996 non-zero value means on. This option is useful if an LDAP
997 I/O operation may be interrupted prematurely, for example
998 by a timer going off, or other interrupt.
1000 LDAP_OPT_PROTOCOL_VERSION (0x11)
1001 Type for invalue parameter: int *
1003 Type for outvalue parameter: int *
1006 This option indicates the version of the LDAP protocol
1010 Expires: 23 August 1999 [Page 18]
1012 C LDAP API C LDAP Application Program Interface 23 February 1999
1015 used when communicating with the primary LDAP server. It
1016 must be one of the constants LDAP_VERSION2 (2) or
1017 LDAP_VERSION3 (3). If no version is set the default is
1020 LDAP_OPT_SERVER_CONTROLS (0x12)
1021 Type for invalue parameter: LDAPControl **
1023 Type for outvalue parameter: LDAPControl ***
1026 A default list of LDAP server controls to be sent with
1027 each request. See the Working With Controls section
1030 LDAP_OPT_CLIENT_CONTROLS (0x13)
1031 Type for invalue parameter: LDAPControl **
1033 Type for outvalue parameter: LDAPControl ***
1036 A default list of client controls that affect the LDAP
1037 session. See the Working With Controls section below.
1039 LDAP_OPT_API_FEATURE_INFO (0x15)
1040 Type for invalue parameter: not applicable (option is READ-
1043 Type for outvalue parameter: LDAPAPIFeatureInfo *
1046 Used to retrieve version information about LDAP API
1047 extended features at execution time. See the section
1048 "Retrieving Information About the API Implementation"
1049 above for more information. This option is READ-ONLY and
1052 LDAP_OPT_HOST_NAME (0x30)
1053 Type for invalue parameter: char *
1055 Type for outvalue parameter: char **
1058 The host name (or list of hosts) for the primary LDAP
1059 server. See the definition of the hostname parameter to
1060 ldap_init() for the allowed syntax.
1062 LDAP_OPT_ERROR_NUMBER (0x31)
1066 Expires: 23 August 1999 [Page 19]
1068 C LDAP API C LDAP Application Program Interface 23 February 1999
1071 Type for invalue parameter: int *
1073 Type for outvalue parameter: int *
1076 The code of the most recent LDAP error that occurred for
1079 LDAP_OPT_ERROR_STRING (0x32)
1080 Type for invalue parameter: char *
1082 Type for outvalue parameter: char **
1085 The message returned with the most recent LDAP error that
1086 occurred for this session.
1089 outvalue The address of a place to put the value of the option. The
1090 actual type of this parameter depends on the setting of the
1091 option parameter. For outvalues of type char ** and LDAP-
1092 Control **, a copy of the data that is associated with the
1093 LDAP session ld is returned; callers should dispose of the
1094 memory by calling ldap_memfree() or ldap_controls_free().
1096 invalue A pointer to the value the option is to be given. The actual
1097 type of this parameter depends on the setting of the option
1098 parameter. The data associated with invalue is copied by the
1099 API implementation to allow callers of the API to dispose of
1100 or otherwise change their copy of the data after a success-
1101 ful call to ldap_set_option(). If a value passed for
1102 invalue is invalid or cannot be accepted by the implementa-
1103 tion, ldap_set_option() should return -1 to indicate an
1106 Both ldap_get_option() and ldap_set_option() return 0 if successful and
1107 -1 if an error occurs.
1109 Standards track documents that extend this specification and specify new
1110 options MUST use values for option macros that are between 0x1000 and
1111 0x3FFF inclusive. Private and experimental extensions MUST use values
1112 for the option macros that are between 0x4000 and 0x7FFF inclusive. All
1113 values below 0x1000 and above 0x7FFF that are not defined in this docu-
1114 ment are reserved and MUST NOT be used.
1122 Expires: 23 August 1999 [Page 20]
1124 C LDAP API C LDAP Application Program Interface 23 February 1999
1127 10.3. Working With Controls
1129 LDAPv3 operations can be extended through the use of controls. Controls
1130 may be sent to a server or returned to the client with any LDAP message.
1131 These controls are referred to as server controls.
1133 The LDAP API also supports a client-side extension mechanism through the
1134 use of client controls. These controls affect the behavior of the LDAP
1135 API only and are never sent to a server. A common data structure is
1136 used to represent both types of controls:
1138 typedef struct ldapcontrol {
1140 struct berval ldctl_value;
1141 char ldctl_iscritical;
1142 } LDAPControl, *PLDAPControl;
1144 The fields in the ldapcontrol structure have the following meanings:
1146 ldctl_oid The control type, represented as a string.
1148 ldctl_value The data associated with the control (if any). To
1149 specify a zero-length value, set ldctl_value.bv_len to
1150 zero and ldctl_value.bv_val to a zero-length string.
1151 To indicate that no data is associated with the con-
1152 trol, set ldctl_value.bv_val to NULL.
1154 ldctl_iscritical Indicates whether the control is critical of not. If
1155 this field is non-zero, the operation will only be car-
1156 ried out if the control is recognized by the server
1157 and/or client. Note that the LDAP unbind and abandon
1158 operations have no server response, so clients SHOULD
1159 NOT mark server controls critical when used with these
1162 Some LDAP API calls allocate an ldapcontrol structure or a NULL-
1163 terminated array of ldapcontrol structures. The following routines can
1164 be used to dispose of a single control or an array of controls:
1166 void ldap_control_free( LDAPControl *ctrl );
1167 void ldap_controls_free( LDAPControl **ctrls );
1169 A set of controls that affect the entire session can be set using the
1170 ldap_set_option() function (see above). A list of controls can also be
1171 passed directly to some LDAP API calls such as ldap_search_ext(), in
1172 which case any controls set for the session through the use of
1173 ldap_set_option() are ignored. Control lists are represented as a NULL-
1174 terminated array of pointers to ldapcontrol structures.
1178 Expires: 23 August 1999 [Page 21]
1180 C LDAP API C LDAP Application Program Interface 23 February 1999
1183 Server controls are defined by LDAPv3 protocol extension documents; for
1184 example, a control has been proposed to support server-side sorting of
1187 One client control is defined in this document (described in the follow-
1188 ing section). Other client controls may be defined in future revisions
1189 of this document or in documents that extend this API.
1192 10.3.1. A Client Control That Governs Referral Processing
1194 As described previously in the section "LDAP Session Handle Options,"
1195 applications can enable and disable automatic chasing of referrals on a
1196 session-wide basic by using the ldap_set_option() function with the
1197 LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer-
1198 ral chasing on per-request basis. A client control with an OID of
1199 1.2.840.113556.1.4.616 exists to provide this functionality.
1201 /* OID for referrals client control */
1202 #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616"
1204 /* Flags for referrals client control value */
1205 #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020
1206 #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040
1208 To create a referrals client control, the ldctl_oid field of an LDAPCon-
1209 trol structure should be set to LDAP_CONTROL_REFERRALS
1210 ("1.2.840.113556.1.4.616") and the ldctl_value field should be set to a
1211 4-octet value that contains a set of flags. The ldctl_value.bv_len
1212 field should always be set to 4. The ldctl_value.bv_val field should
1213 point to a 4-octet integer flags value. This flags value can be set to
1214 zero to disable automatic chasing of referrals and LDAPv3 references
1215 altogether. Alternatively, the flags value can be set to the value
1216 LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020) to indicate that only
1217 LDAPv3 search continuation references should be automatically chased by
1218 the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS
1219 (0x00000040) to indicate that only LDAPv3 referrals should be automati-
1220 cally chased, or the logical OR of the two flag values (0x00000060) to
1221 indicate that both referrals and references should be automatically
1225 10.4. Authenticating to the directory
1227 The following functions are used to authenticate an LDAP client to an
1228 LDAP directory server.
1230 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
1234 Expires: 23 August 1999 [Page 22]
1236 C LDAP API C LDAP Application Program Interface 23 February 1999
1239 general and extensible authentication over LDAP through the use of the
1240 Simple Authentication Security Layer [8]. The routines both take the dn
1241 to bind as, the method to use, as a dotted-string representation of an
1242 OID identifying the method, and a struct berval holding the credentials.
1243 The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to
1244 request simple authentication, or the simplified routines
1245 ldap_simple_bind() or ldap_simple_bind_s() can be used.
1250 const char *mechanism,
1251 const struct berval *cred,
1252 LDAPControl **serverctrls,
1253 LDAPControl **clientctrls,
1257 int ldap_sasl_bind_s(
1260 const char *mechanism,
1261 const struct berval *cred,
1262 LDAPControl **serverctrls,
1263 LDAPControl **clientctrls,
1264 struct berval **servercredp
1267 int ldap_simple_bind(
1273 int ldap_simple_bind_s(
1279 The use of the following routines is deprecated:
1281 int ldap_bind( LDAP *ld, const char *dn, const char *cred,
1284 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
1290 Expires: 23 August 1999 [Page 23]
1292 C LDAP API C LDAP Application Program Interface 23 February 1999
1295 int ldap_kerberos_bind( LDAP *ld, const char *dn );
1297 int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
1301 ld The session handle.
1303 dn The name of the entry to bind as.
1305 mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica-
1306 tion, or a text string identifying the SASL method.
1308 cred The credentials with which to authenticate. Arbitrary
1309 credentials can be passed using this parameter. The format
1310 and content of the credentials depends on the setting of
1311 the mechanism parameter.
1313 passwd For ldap_simple_bind(), the password to compare to the
1314 entry's userPassword attribute.
1316 serverctrls List of LDAP server controls.
1318 clientctrls List of client controls.
1320 msgidp This result parameter will be set to the message id of the
1321 request if the ldap_sasl_bind() call succeeds.
1323 servercredp This result parameter will be filled in with the creden-
1324 tials passed back by the server for mutual authentication,
1325 if given. An allocated berval structure is returned that
1326 should be disposed of by calling ber_bvfree(). NULL may be
1327 passed to ignore this field.
1329 Additional parameters for the deprecated routines are not described.
1330 Interested readers are referred to RFC 1823.
1332 The ldap_sasl_bind() function initiates an asynchronous bind operation
1333 and returns the constant LDAP_SUCCESS if the request was successfully
1334 sent, or another LDAP error code if not. See the section below on error
1335 handling for more information about possible errors and how to interpret
1336 them. If successful, ldap_sasl_bind() places the message id of the
1337 request in *msgidp. A subsequent call to ldap_result(), described below,
1338 can be used to obtain the result of the bind.
1340 The ldap_simple_bind() function initiates a simple asynchronous bind
1341 operation and returns the message id of the operation initiated. A sub-
1342 sequent call to ldap_result(), described below, can be used to obtain
1346 Expires: 23 August 1999 [Page 24]
1348 C LDAP API C LDAP Application Program Interface 23 February 1999
1351 the result of the bind. In case of error, ldap_simple_bind() will return
1352 -1, setting the session error parameters in the LDAP structure appropri-
1355 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
1356 both return the result of the operation, either the constant
1357 LDAP_SUCCESS if the operation was successful, or another LDAP error code
1358 if it was not. See the section below on error handling for more informa-
1359 tion about possible errors and how to interpret them.
1361 Note that if an LDAPv2 server is contacted, no other operations over the
1362 connection should be attempted before a bind call has successfully com-
1365 Subsequent bind calls can be used to re-authenticate over the same con-
1366 nection, and multistep SASL sequences can be accomplished through a
1367 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
1370 10.5. Closing the session
1372 The following functions are used to unbind from the directory, close
1373 open connections, and dispose of the session handle.
1375 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
1376 LDAPControl **clientctrls );
1378 int ldap_unbind( LDAP *ld );
1380 int ldap_unbind_s( LDAP *ld );
1384 ld The session handle.
1386 serverctrls List of LDAP server controls.
1388 clientctrls List of client controls.
1390 The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn-
1391 chronously in the sense that they send an unbind request to the server,
1392 close all open connections associated with the LDAP session handle, and
1393 dispose of all resources associated with the session handle before
1394 returning. Note, however, that there is no server response to an LDAP
1395 unbind operation. All three of the unbind functions return LDAP_SUCCESS
1396 (or another LDAP error code if the request cannot be sent to the LDAP
1397 server). After a call to one of the unbind functions, the session han-
1398 dle ld is invalid and it is illegal to make any further LDAP API calls
1402 Expires: 23 August 1999 [Page 25]
1404 C LDAP API C LDAP Application Program Interface 23 February 1999
1409 The ldap_unbind() and ldap_unbind_s() functions behave identically. The
1410 ldap_unbind_ext() function allows server and client controls to be
1411 included explicitly, but note that since there is no server response to
1412 an unbind request there is no way to receive a response to a server con-
1413 trol sent with an unbind request.
1419 The following functions are used to search the LDAP directory, returning
1420 a requested set of attributes for each entry matched. There are five
1423 int ldap_search_ext(
1430 LDAPControl **serverctrls,
1431 LDAPControl **clientctrls,
1432 struct timeval *timeout,
1437 int ldap_search_ext_s(
1444 LDAPControl **serverctrls,
1445 LDAPControl **clientctrls,
1446 struct timeval *timeout,
1458 Expires: 23 August 1999 [Page 26]
1460 C LDAP API C LDAP Application Program Interface 23 February 1999
1485 struct timeval *timeout,
1491 ld The session handle.
1493 base The dn of the entry at which to start the search.
1495 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
1496 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
1499 filter A character string as described in [3], representing the
1500 search filter. The value NULL can be passed to indicate
1501 that the filter "(objectclass=*)" which matches all entries
1502 should be used. Note that if the caller of the API is
1503 using LDAPv2, only a subset of the filter functionality
1504 described in [3] can be successfully used.
1506 attrs A NULL-terminated array of strings indicating which attri-
1507 butes to return for each matching entry. Passing NULL for
1508 this parameter causes all available user attributes to be
1509 retrieved. The special constant string LDAP_NO_ATTRS
1510 ("1.1") can be used as the only string in the array to
1514 Expires: 23 August 1999 [Page 27]
1516 C LDAP API C LDAP Application Program Interface 23 February 1999
1519 indicate that no attribute types should be returned by the
1520 server. The special constant string LDAP_ALL_USER_ATTRS
1521 ("*") can be used in the attrs array along with the names
1522 of some operational attributes to indicate that all user
1523 attributes plus the listed operational attributes should be
1526 attrsonly A boolean value that should be zero if both attribute types
1527 and values are to be returned, non-zero if only types are
1530 timeout For the ldap_search_st() function, this specifies the local
1531 search timeout value (if it is NULL, the timeout is infin-
1532 ite). For the ldap_search_ext() and ldap_search_ext_s()
1533 functions, this specifies both the local search timeout
1534 value and the operation time limit that is sent to the
1535 server within the search request. For the
1536 ldap_search_ext() and ldap_search_ext_s() functions, pass-
1537 ing a NULL value for timeout causes the global default
1538 timeout stored in the LDAP session handle (set by using
1539 ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to
1540 be sent to the server with the request but an infinite
1541 local search timeout to be used.
1543 sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls,
1544 this is a limit on the number of entries to return from the
1545 search. A value of LDAP_NO_LIMIT (0) means no limit.
1547 res For the synchronous calls, this is a result parameter which
1548 will contain the results of the search upon completion of
1549 the call. If no results are returned, *res is set to NULL.
1551 serverctrls List of LDAP server controls.
1553 clientctrls List of client controls.
1555 msgidp This result parameter will be set to the message id of the
1556 request if the ldap_search_ext() call succeeds.
1558 There are three options in the session handle ld which potentially
1559 affect how the search is performed. They are:
1562 A limit on the number of entries to return from the search.
1563 A value of LDAP_NO_LIMIT (0) means no limit. Note that the
1564 value from the session handle is ignored when using the
1565 ldap_search_ext() or ldap_search_ext_s() functions.
1570 Expires: 23 August 1999 [Page 28]
1572 C LDAP API C LDAP Application Program Interface 23 February 1999
1576 A limit on the number of seconds to spend on the search. A
1577 value of LDAP_NO_LIMIT (0) means no limit. Note that the
1578 value from the session handle is ignored when using the
1579 ldap_search_ext() or ldap_search_ext_s() functions.
1582 One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
1583 (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
1584 (0x03), specifying how aliases should be handled during the
1585 search. The LDAP_DEREF_SEARCHING value means aliases should
1586 be dereferenced during the search but not when locating the
1587 base object of the search. The LDAP_DEREF_FINDING value
1588 means aliases should be dereferenced when locating the base
1589 object but not during the search.
1591 The ldap_search_ext() function initiates an asynchronous search opera-
1592 tion and returns the constant LDAP_SUCCESS if the request was success-
1593 fully sent, or another LDAP error code if not. See the section below on
1594 error handling for more information about possible errors and how to
1595 interpret them. If successful, ldap_search_ext() places the message id
1596 of the request in *msgidp. A subsequent call to ldap_result(), described
1597 below, can be used to obtain the results from the search. These results
1598 can be parsed using the result parsing routines described in detail
1601 Similar to ldap_search_ext(), the ldap_search() function initiates an
1602 asynchronous search operation and returns the message id of the opera-
1603 tion initiated. As for ldap_search_ext(), a subsequent call to
1604 ldap_result(), described below, can be used to obtain the result of the
1605 bind. In case of error, ldap_search() will return -1, setting the ses-
1606 sion error parameters in the LDAP structure appropriately.
1608 The synchronous ldap_search_ext_s(), ldap_search_s(), and
1609 ldap_search_st() functions all return the result of the operation,
1610 either the constant LDAP_SUCCESS if the operation was successful, or
1611 another LDAP error code if it was not. See the section below on error
1612 handling for more information about possible errors and how to interpret
1613 them. Entries returned from the search (if any) are contained in the
1614 res parameter. This parameter is opaque to the caller. Entries, attri-
1615 butes, values, etc., should be extracted by calling the parsing routines
1616 described below. The results contained in res should be freed when no
1617 longer in use by calling ldap_msgfree(), described later.
1619 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
1620 server controls, client controls, and allow varying size and time limits
1621 to be easily specified for each search operation. The ldap_search_st()
1622 function is identical to ldap_search_s() except that it takes an
1626 Expires: 23 August 1999 [Page 29]
1628 C LDAP API C LDAP Application Program Interface 23 February 1999
1631 additional parameter specifying a local timeout for the search. The
1632 local search timeout is used to limit the amount of time the API imple-
1633 mentation will wait for a search to complete. After the local search
1634 timeout expires, the API implementation will send an abandon operation
1635 to abort the search operation.
1637 10.7. Reading an Entry
1639 LDAP does not support a read operation directly. Instead, this operation
1640 is emulated by a search with base set to the DN of the entry to read,
1641 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or
1642 NULL. attrs contains the list of attributes to return.
1645 10.8. Listing the Children of an Entry
1647 LDAP does not support a list operation directly. Instead, this operation
1648 is emulated by a search with base set to the DN of the entry to list,
1649 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or
1650 NULL. attrs contains the list of attributes to return for each child
1653 10.9. Comparing a Value Against an Entry
1655 The following routines are used to compare a given attribute value
1656 assertion against an LDAP entry. There are four variations:
1658 int ldap_compare_ext(
1662 struct berval *bvalue
1663 LDAPControl **serverctrls,
1664 LDAPControl **clientctrls,
1668 int ldap_compare_ext_s(
1672 struct berval *bvalue,
1673 LDAPControl **serverctrls,
1674 LDAPControl **clientctrls
1682 Expires: 23 August 1999 [Page 30]
1684 C LDAP API C LDAP Application Program Interface 23 February 1999
1701 ld The session handle.
1703 dn The name of the entry to compare against.
1705 attr The attribute to compare against.
1707 bvalue The attribute value to compare against those found in the
1708 given entry. This parameter is used in the extended rou-
1709 tines and is a pointer to a struct berval so it is possible
1710 to compare binary values.
1712 value A string attribute value to compare against, used by the
1713 ldap_compare() and ldap_compare_s() functions. Use
1714 ldap_compare_ext() or ldap_compare_ext_s() if you need to
1715 compare binary values.
1717 serverctrls List of LDAP server controls.
1719 clientctrls List of client controls.
1721 msgidp This result parameter will be set to the message id of the
1722 request if the ldap_compare_ext() call succeeds.
1724 The ldap_compare_ext() function initiates an asynchronous compare opera-
1725 tion and returns the constant LDAP_SUCCESS if the request was success-
1726 fully sent, or another LDAP error code if not. See the section below on
1727 error handling for more information about possible errors and how to
1728 interpret them. If successful, ldap_compare_ext() places the message id
1729 of the request in *msgidp. A subsequent call to ldap_result(), described
1730 below, can be used to obtain the result of the compare.
1732 Similar to ldap_compare_ext(), the ldap_compare() function initiates an
1733 asynchronous compare operation and returns the message id of the opera-
1734 tion initiated. As for ldap_compare_ext(), a subsequent call to
1738 Expires: 23 August 1999 [Page 31]
1740 C LDAP API C LDAP Application Program Interface 23 February 1999
1743 ldap_result(), described below, can be used to obtain the result of the
1744 bind. In case of error, ldap_compare() will return -1, setting the ses-
1745 sion error parameters in the LDAP structure appropriately.
1747 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
1748 return the result of the operation, either the constant LDAP_SUCCESS if
1749 the operation was successful, or another LDAP error code if it was not.
1750 See the section below on error handling for more information about pos-
1751 sible errors and how to interpret them.
1753 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
1754 server controls and client controls.
1757 10.10. Modifying an entry
1759 The following routines are used to modify an existing LDAP entry. There
1760 are four variations:
1762 typedef struct ldapmod {
1766 char **modv_strvals;
1767 struct berval **modv_bvals;
1770 #define mod_values mod_vals.modv_strvals
1771 #define mod_bvalues mod_vals.modv_bvals
1773 int ldap_modify_ext(
1777 LDAPControl **serverctrls,
1778 LDAPControl **clientctrls,
1782 int ldap_modify_ext_s(
1786 LDAPControl **serverctrls,
1787 LDAPControl **clientctrls
1794 Expires: 23 August 1999 [Page 32]
1796 C LDAP API C LDAP Application Program Interface 23 February 1999
1812 ld The session handle.
1814 dn The name of the entry to modify.
1816 mods A NULL-terminated array of modifications to make to the
1819 serverctrls List of LDAP server controls.
1821 clientctrls List of client controls.
1823 msgidp This result parameter will be set to the message id of the
1824 request if the ldap_modify_ext() call succeeds.
1826 The fields in the LDAPMod structure have the following meanings:
1828 mod_op The modification operation to perform. It should be one of
1829 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
1830 LDAP_MOD_REPLACE (0x02). This field also indicates the
1831 type of values included in the mod_vals union. It is logi-
1832 cally ORed with LDAP_MOD_BVALUES (0x80) to select the
1833 mod_bvalues form. Otherwise, the mod_values form is used.
1835 mod_type The type of the attribute to modify.
1837 mod_vals The values (if any) to add, delete, or replace. Only one of
1838 the mod_values or mod_bvalues variants should be used,
1839 selected by ORing the mod_op field with the constant
1840 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
1841 zero-terminated strings and mod_bvalues is a NULL-
1842 terminated array of berval structures that can be used to
1843 pass binary values such as images.
1845 For LDAP_MOD_ADD modifications, the given values are added to the
1846 entry, creating the attribute if necessary.
1850 Expires: 23 August 1999 [Page 33]
1852 C LDAP API C LDAP Application Program Interface 23 February 1999
1855 For LDAP_MOD_DELETE modifications, the given values are deleted from the
1856 entry, removing the attribute if no values remain. If the entire attri-
1857 bute is to be deleted, the mod_vals field should be set to NULL.
1859 For LDAP_MOD_REPLACE modifications, the attribute will have the listed
1860 values after the modification, having been created if necessary, or
1861 removed if the mod_vals field is NULL. All modifications are performed
1862 in the order in which they are listed.
1864 The ldap_modify_ext() function initiates an asynchronous modify opera-
1865 tion and returns the constant LDAP_SUCCESS if the request was success-
1866 fully sent, or another LDAP error code if not. See the section below on
1867 error handling for more information about possible errors and how to
1868 interpret them. If successful, ldap_modify_ext() places the message id
1869 of the request in *msgidp. A subsequent call to ldap_result(), described
1870 below, can be used to obtain the result of the modify.
1872 Similar to ldap_modify_ext(), the ldap_modify() function initiates an
1873 asynchronous modify operation and returns the message id of the opera-
1874 tion initiated. As for ldap_modify_ext(), a subsequent call to
1875 ldap_result(), described below, can be used to obtain the result of the
1876 modify. In case of error, ldap_modify() will return -1, setting the ses-
1877 sion error parameters in the LDAP structure appropriately.
1879 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
1880 return the result of the operation, either the constant LDAP_SUCCESS if
1881 the operation was successful, or another LDAP error code if it was not.
1882 See the section below on error handling for more information about pos-
1883 sible errors and how to interpret them.
1885 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
1886 server controls and client controls.
1889 10.11. Modifying the Name of an Entry
1891 In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and
1892 ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
1893 They could only be used to change the least significant component of a
1894 name (the RDN or relative distinguished name). LDAPv3 provides the
1895 Modify DN protocol operation that allows more general name change
1896 access. The ldap_rename() and ldap_rename_s() routines are used to
1897 change the name of an entry, and the use of the ldap_modrdn(),
1898 ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre-
1906 Expires: 23 August 1999 [Page 34]
1908 C LDAP API C LDAP Application Program Interface 23 February 1999
1913 const char *newparent,
1915 LDAPControl **serverctrls,
1916 LDAPControl **clientctrls,
1924 const char *newparent,
1926 LDAPControl **serverctrls,
1927 LDAPControl **clientctrls
1930 Use of the following routines is deprecated.
1957 ld The session handle.
1962 Expires: 23 August 1999 [Page 35]
1964 C LDAP API C LDAP Application Program Interface 23 February 1999
1967 dn The name of the entry whose DN is to be changed.
1969 newrdn The new RDN to give the entry.
1971 newparent The new parent, or superior entry. If this parameter is
1972 NULL, only the RDN of the entry is changed. The root DN
1973 may be specified by passing a zero length string, "". The
1974 newparent parameter should always be NULL when using ver-
1975 sion 2 of the LDAP protocol; otherwise the server's
1976 behavior is undefined.
1978 deleteoldrdn This parameter only has meaning on the rename routines if
1979 newrdn is different than the old RDN. It is a boolean
1980 value, if non-zero indicating that the old RDN value(s)
1981 should be removed, if zero indicating that the old RDN
1982 value(s) should be retained as non-distinguished values of
1985 serverctrls List of LDAP server controls.
1987 clientctrls List of client controls.
1989 msgidp This result parameter will be set to the message id of the
1990 request if the ldap_rename() call succeeds.
1992 The ldap_rename() function initiates an asynchronous modify DN operation
1993 and returns the constant LDAP_SUCCESS if the request was successfully
1994 sent, or another LDAP error code if not. See the section below on error
1995 handling for more information about possible errors and how to interpret
1996 them. If successful, ldap_rename() places the DN message id of the
1997 request in *msgidp. A subsequent call to ldap_result(), described below,
1998 can be used to obtain the result of the rename.
2000 The synchronous ldap_rename_s() returns the result of the operation,
2001 either the constant LDAP_SUCCESS if the operation was successful, or
2002 another LDAP error code if it was not. See the section below on error
2003 handling for more information about possible errors and how to interpret
2006 The ldap_rename() and ldap_rename_s() functions both support LDAPv3
2007 server controls and client controls.
2010 10.12. Adding an entry
2012 The following functions are used to add entries to the LDAP directory.
2013 There are four variations:
2018 Expires: 23 August 1999 [Page 36]
2020 C LDAP API C LDAP Application Program Interface 23 February 1999
2027 LDAPControl **serverctrls,
2028 LDAPControl **clientctrls,
2036 LDAPControl **serverctrls,
2037 LDAPControl **clientctrls
2054 ld The session handle.
2056 dn The name of the entry to add.
2058 attrs The entry's attributes, specified using the LDAPMod struc-
2059 ture defined for ldap_modify(). The mod_type and mod_vals
2060 fields should be filled in. The mod_op field is ignored
2061 unless ORed with the constant LDAP_MOD_BVALUES, used to
2062 select the mod_bvalues case of the mod_vals union.
2064 serverctrls List of LDAP server controls.
2066 clientctrls List of client controls.
2068 msgidp This result parameter will be set to the message id of the
2069 request if the ldap_add_ext() call succeeds.
2074 Expires: 23 August 1999 [Page 37]
2076 C LDAP API C LDAP Application Program Interface 23 February 1999
2079 Note that the parent of the entry being added must already exist or the
2080 parent must be empty (i.e., equal to the root DN) for an add to succeed.
2082 The ldap_add_ext() function initiates an asynchronous add operation and
2083 returns the constant LDAP_SUCCESS if the request was successfully sent,
2084 or another LDAP error code if not. See the section below on error han-
2085 dling for more information about possible errors and how to interpret
2086 them. If successful, ldap_add_ext() places the message id of the
2087 request in *msgidp. A subsequent call to ldap_result(), described below,
2088 can be used to obtain the result of the add.
2090 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
2091 chronous add operation and returns the message id of the operation ini-
2092 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(),
2093 described below, can be used to obtain the result of the add. In case of
2094 error, ldap_add() will return -1, setting the session error parameters
2095 in the LDAP structure appropriately.
2097 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
2098 the result of the operation, either the constant LDAP_SUCCESS if the
2099 operation was successful, or another LDAP error code if it was not. See
2100 the section below on error handling for more information about possible
2101 errors and how to interpret them.
2103 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
2104 controls and client controls.
2108 10.13. Deleting an entry
2110 The following functions are used to delete a leaf entry from the LDAP
2111 directory. There are four variations:
2113 int ldap_delete_ext(
2116 LDAPControl **serverctrls,
2117 LDAPControl **clientctrls,
2121 int ldap_delete_ext_s(
2124 LDAPControl **serverctrls,
2125 LDAPControl **clientctrls
2130 Expires: 23 August 1999 [Page 38]
2132 C LDAP API C LDAP Application Program Interface 23 February 1999
2148 ld The session handle.
2150 dn The name of the entry to delete.
2152 serverctrls List of LDAP server controls.
2154 clientctrls List of client controls.
2156 msgidp This result parameter will be set to the message id of the
2157 request if the ldap_delete_ext() call succeeds.
2159 Note that the entry to delete must be a leaf entry (i.e., it must have
2160 no children). Deletion of entire subtrees in a single operation is not
2163 The ldap_delete_ext() function initiates an asynchronous delete opera-
2164 tion and returns the constant LDAP_SUCCESS if the request was success-
2165 fully sent, or another LDAP error code if not. See the section below on
2166 error handling for more information about possible errors and how to
2167 interpret them. If successful, ldap_delete_ext() places the message id
2168 of the request in *msgidp. A subsequent call to ldap_result(), described
2169 below, can be used to obtain the result of the delete.
2171 Similar to ldap_delete_ext(), the ldap_delete() function initiates an
2172 asynchronous delete operation and returns the message id of the opera-
2173 tion initiated. As for ldap_delete_ext(), a subsequent call to
2174 ldap_result(), described below, can be used to obtain the result of the
2175 delete. In case of error, ldap_delete() will return -1, setting the ses-
2176 sion error parameters in the LDAP structure appropriately.
2178 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
2179 return the result of the operation, either the constant LDAP_SUCCESS if
2180 the operation was successful, or another LDAP error code if it was not.
2181 See the section below on error handling for more information about pos-
2182 sible errors and how to interpret them.
2186 Expires: 23 August 1999 [Page 39]
2188 C LDAP API C LDAP Application Program Interface 23 February 1999
2191 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
2192 server controls and client controls.
2195 10.14. Extended Operations
2197 The ldap_extended_operation() and ldap_extended_operation_s() routines
2198 allow extended LDAP operations to be passed to the server, providing a
2199 general protocol extensibility mechanism.
2201 int ldap_extended_operation(
2204 struct berval *exdata,
2205 LDAPControl **serverctrls,
2206 LDAPControl **clientctrls,
2210 int ldap_extended_operation_s(
2213 struct berval *exdata,
2214 LDAPControl **serverctrls,
2215 LDAPControl **clientctrls,
2217 struct berval **retdatap
2222 ld The session handle.
2224 requestoid The dotted-OID text string naming the request.
2226 requestdata The arbitrary data required by the operation (if NULL, no
2227 data is sent to the server).
2229 serverctrls List of LDAP server controls.
2231 clientctrls List of client controls.
2233 msgidp This result parameter will be set to the message id of the
2234 request if the ldap_extended_operation() call succeeds.
2236 retoidp Pointer to a character string that will be set to an allo-
2237 cated, dotted-OID text string returned by the server. This
2238 string should be disposed of using the ldap_memfree()
2242 Expires: 23 August 1999 [Page 40]
2244 C LDAP API C LDAP Application Program Interface 23 February 1999
2247 function. If no OID was returned, *retoidp is set to NULL.
2249 retdatap Pointer to a berval structure pointer that will be set an
2250 allocated copy of the data returned by the server. This
2251 struct berval should be disposed of using ber_bvfree(). If
2252 no data is returned, *retdatap is set to NULL.
2254 The ldap_extended_operation() function initiates an asynchronous
2255 extended operation and returns the constant LDAP_SUCCESS if the request
2256 was successfully sent, or another LDAP error code if not. See the sec-
2257 tion below on error handling for more information about possible errors
2258 and how to interpret them. If successful, ldap_extended_operation()
2259 places the message id of the request in *msgidp. A subsequent call to
2260 ldap_result(), described below, can be used to obtain the result of the
2261 extended operation which can be passed to ldap_parse_extended_result()
2262 to obtain the OID and data contained in the response.
2264 The synchronous ldap_extended_operation_s() function returns the result
2265 of the operation, either the constant LDAP_SUCCESS if the operation was
2266 successful, or another LDAP error code if it was not. See the section
2267 below on error handling for more information about possible errors and
2268 how to interpret them. The retoid and retdata parameters are filled in
2269 with the OID and data from the response. If no OID or data was
2270 returned, these parameters are set to NULL.
2272 The ldap_extended_operation() and ldap_extended_operation_s() functions
2273 both support LDAPv3 server controls and client controls.
2276 11. Abandoning An Operation
2278 The following calls are used to abandon an operation in progress:
2280 int ldap_abandon_ext(
2283 LDAPControl **serverctrls,
2284 LDAPControl **clientctrls
2293 ld The session handle.
2298 Expires: 23 August 1999 [Page 41]
2300 C LDAP API C LDAP Application Program Interface 23 February 1999
2303 msgid The message id of the request to be abandoned.
2305 serverctrls List of LDAP server controls.
2307 clientctrls List of client controls.
2309 ldap_abandon_ext() abandons the operation with message id msgid and
2310 returns the constant LDAP_SUCCESS if the abandon was successful or
2311 another LDAP error code if not. See the section below on error handling
2312 for more information about possible errors and how to interpret them.
2314 ldap_abandon() is identical to ldap_abandon_ext() except that it does
2315 not accept client or server controls and it returns zero if the abandon
2316 was successful, -1 otherwise.
2318 After a successful call to ldap_abandon() or ldap_abandon_ext(), results
2319 with the given message id are never returned from a subsequent call to
2320 ldap_result(). There is no server response to LDAP abandon operations.
2323 12. Obtaining Results and Peeking Inside LDAP Messages
2325 ldap_result() is used to obtain the result of a previous asynchronously
2326 initiated operation. Note that depending on how it is called,
2327 ldap_result() may actually return a list or "chain" of result messages.
2328 The ldap_result() function only returns messages for a single request,
2329 so for all LDAP operations other than search only one result message is
2330 expected; that is, the only time the "result chain" may contain more
2331 than one message is if results from a search operation are returned.
2332 Once a chain of messages has been returned to the caller, it is no
2333 longer tied in any caller-visible way to the LDAP request that produced
2334 it. Therefore, a chain of messages returned by calling ldap_result() or
2335 by calling a synchronous search routine will never be affected by subse-
2336 quent LDAP API calls (except for ldap_msgfree() which is used to dispose
2337 of a chain of messages).
2339 ldap_msgfree() frees the result messages (possibly an entire chain of
2340 messages) obtained from a previous call to ldap_result() or from a call
2341 to a synchronous search routine.
2343 ldap_msgtype() returns the type of an LDAP message. ldap_msgid()
2344 returns the message ID of an LDAP message.
2350 struct timeval *timeout,
2354 Expires: 23 August 1999 [Page 42]
2356 C LDAP API C LDAP Application Program Interface 23 February 1999
2362 int ldap_msgfree( LDAPMessage *res );
2364 int ldap_msgtype( LDAPMessage *res );
2366 int ldap_msgid( LDAPMessage *res );
2370 ld The session handle.
2372 msgid The message id of the operation whose results are to be
2373 returned, or the constant LDAP_RES_ANY (-1) if any result is
2376 all Specifies how many messages will be retrieved in a single call
2377 to ldap_result(). This parameter only has meaning for search
2378 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
2379 message at a time. Pass LDAP_MSG_ALL (0x01) to request that
2380 all results of a search be received before returning all
2381 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to
2382 indicate that all messages retrieved so far should be returned
2383 in the result chain.
2385 timeout A timeout specifying how long to wait for results to be
2386 returned. A NULL value causes ldap_result() to block until
2387 results are available. A timeout value of zero seconds speci-
2388 fies a polling behavior.
2390 res For ldap_result(), a result parameter that will contain the
2391 result(s) of the operation. If no results are returned, *res is
2392 set to NULL. For ldap_msgfree(), the result chain to be freed,
2393 obtained from a previous call to ldap_result(),
2394 ldap_search_s(), or ldap_search_st(). If res is NULL, nothing
2395 is done and ldap_msgfree() returns zero.
2397 Upon successful completion, ldap_result() returns the type of the first
2398 result returned in the res parameter. This will be one of the following
2401 LDAP_RES_BIND (0x61)
2402 LDAP_RES_SEARCH_ENTRY (0x64)
2403 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3
2404 LDAP_RES_SEARCH_RESULT (0x65)
2405 LDAP_RES_MODIFY (0x67)
2410 Expires: 23 August 1999 [Page 43]
2412 C LDAP API C LDAP Application Program Interface 23 February 1999
2415 LDAP_RES_DELETE (0x6B)
2416 LDAP_RES_MODDN (0x6D)
2417 LDAP_RES_COMPARE (0x6F)
2418 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3
2420 ldap_result() returns 0 if the timeout expired and -1 if an error
2421 occurs, in which case the error parameters of the LDAP session handle
2422 will be set accordingly.
2424 ldap_msgfree() frees the result structure pointed to by res and returns
2425 the type of the message it freed. If res is NULL, nothing is done and
2426 the value zero is returned.
2428 ldap_msgtype() returns the type of the LDAP message it is passed as a
2429 parameter. The type will be one of the types listed above, or -1 on
2432 ldap_msgid() returns the message ID associated with the LDAP message
2433 passed as a parameter.
2436 13. Handling Errors and Parsing Results
2438 The following calls are used to extract information from results and
2439 handle errors returned by other LDAP API routines. Note that
2440 ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ-
2441 ically be used in addition to ldap_parse_result() to retrieve all the
2442 result information from SASL Bind and Extended Operations respectively.
2444 int ldap_parse_result(
2451 LDAPControl ***serverctrlsp,
2455 int ldap_parse_sasl_bind_result(
2458 struct berval **servercredp,
2462 int ldap_parse_extended_result(
2466 Expires: 23 August 1999 [Page 44]
2468 C LDAP API C LDAP Application Program Interface 23 February 1999
2474 struct berval **retdatap,
2478 char *ldap_err2string( int err );
2480 The use of the following routines is deprecated.
2482 int ldap_result2error(
2488 void ldap_perror( LDAP *ld, const char *msg );
2492 ld The session handle.
2494 res The result of an LDAP operation as returned by
2495 ldap_result() or one of the synchronous API operation
2498 errcodep This result parameter will be filled in with the LDAP error
2499 code field from the LDAPMessage message. This is the indi-
2500 cation from the server of the outcome of the operation.
2501 NULL may be passed to ignore this field.
2503 matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result
2504 parameter will be filled in with a DN indicating how much
2505 of the name in the request was recognized. NULL may be
2506 passed to ignore this field. The matched DN string should
2507 be freed by calling ldap_memfree() which is described later
2510 errmsgp This result parameter will be filled in with the contents
2511 of the error message field from the LDAPMessage message.
2512 The error message string should be freed by calling
2513 ldap_memfree() which is described later in this document.
2514 NULL may be passed to ignore this field.
2516 referralsp This result parameter will be filled in with the contents
2517 of the referrals field from the LDAPMessage message, indi-
2518 cating zero or more alternate LDAP servers where the
2522 Expires: 23 August 1999 [Page 45]
2524 C LDAP API C LDAP Application Program Interface 23 February 1999
2527 request should be retried. The referrals array should be
2528 freed by calling ldap_value_free() which is described later
2529 in this document. NULL may be passed to ignore this field.
2531 serverctrlsp This result parameter will be filled in with an allocated
2532 array of controls copied out of the LDAPMessage message.
2533 The control array should be freed by calling
2534 ldap_controls_free() which was described earlier.
2536 freeit A boolean that determines whether the res parameter is
2537 disposed of or not. Pass any non-zero value to have these
2538 routines free res after extracting the requested informa-
2539 tion. This is provided as a convenience; you can also use
2540 ldap_msgfree() to free the result later. If freeit is
2541 non-zero, the entire chain of messages represented by res
2544 servercredp For SASL bind results, this result parameter will be filled
2545 in with the credentials passed back by the server for
2546 mutual authentication, if given. An allocated berval struc-
2547 ture is returned that should be disposed of by calling
2548 ber_bvfree(). NULL may be passed to ignore this field.
2550 retoidp For extended results, this result parameter will be filled
2551 in with the dotted-OID text representation of the name of
2552 the extended operation response. This string should be
2553 disposed of by calling ldap_memfree(). NULL may be passed
2554 to ignore this field.
2556 retdatap For extended results, this result parameter will be filled
2557 in with a pointer to a struct berval containing the data in
2558 the extended operation response. It should be disposed of
2559 by calling ber_bvfree(). NULL may be passed to ignore this
2562 err For ldap_err2string(), an LDAP error code, as returned by
2563 ldap_parse_result() or another LDAP API call.
2565 Additional parameters for the deprecated routines are not described.
2566 Interested readers are referred to RFC 1823.
2568 All three of the ldap_parse_*_result() routines skip over messages of
2569 type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking
2570 for a result message to parse. They return the constant LDAP_SUCCESS if
2571 the result was successfully parsed and another LDAP error code if not.
2572 Note that the LDAP error code that indicates the outcome of the opera-
2573 tion performed by the server is placed in the errcodep
2574 ldap_parse_result() parameter. If a chain of messages that contains
2578 Expires: 23 August 1999 [Page 46]
2580 C LDAP API C LDAP Application Program Interface 23 February 1999
2583 more than one result message is passed to these routines they always
2584 operate on the first result in the chain.
2586 ldap_err2string() is used to convert a numeric LDAP error code, as
2587 returned by one of the three ldap_parse_*_result() routines, or one of
2588 the synchronous API operation calls, into an informative zero-terminated
2589 character string message describing the error. It returns a pointer to
2593 14. Stepping Through a List of Results
2595 The ldap_first_message() and ldap_next_message() routines are used to
2596 step through the list of messages in a result chain returned by
2597 ldap_result(). For search operations, the result chain may actually
2598 include referral messages, entry messages, and result messages.
2599 ldap_count_messages() is used to count the number of messages returned.
2600 The ldap_msgtype() function, described above, can be used to distinguish
2601 between the different message types.
2603 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
2605 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
2607 int ldap_count_messages( LDAP *ld, LDAPMessage *res );
2611 ld The session handle.
2613 res The result chain, as obtained by a call to one of the synchronous
2614 search routines or ldap_result().
2616 msg The message returned by a previous call to ldap_first_message()
2617 or ldap_next_message().
2619 ldap_first_message() and ldap_next_message() will return NULL when no
2620 more messages exist in the result set to be returned. NULL is also
2621 returned if an error occurs while stepping through the entries, in which
2622 case the error parameters in the session handle ld will be set to indi-
2625 ldap_count_messages() returns the number of messages contained in a
2626 chain of results. It can also be used to count the number of messages
2627 that remain in a chain if called with a message, entry, or reference
2628 returned by ldap_first_message(), ldap_next_message(),
2629 ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
2630 ldap_next_reference().
2634 Expires: 23 August 1999 [Page 47]
2636 C LDAP API C LDAP Application Program Interface 23 February 1999
2639 15. Parsing Search Results
2641 The following calls are used to parse the entries and references
2642 returned by ldap_search() and friends. These results are returned in an
2643 opaque structure that should only be accessed by calling the routines
2644 described below. Routines are provided to step through the entries and
2645 references returned, step through the attributes of an entry, retrieve
2646 the name of an entry, and retrieve the values associated with a given
2647 attribute in an entry.
2650 15.1. Stepping Through a List of Entries or References
2652 The ldap_first_entry() and ldap_next_entry() routines are used to step
2653 through and retrieve the list of entries from a search result chain.
2654 The ldap_first_reference() and ldap_next_reference() routines are used
2655 to step through and retrieve the list of continuation references from a
2656 search result chain. ldap_count_entries() is used to count the number
2657 of entries returned. ldap_count_references() is used to count the number
2658 of references returned.
2660 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
2662 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
2664 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
2666 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
2668 int ldap_count_entries( LDAP *ld, LDAPMessage *res );
2670 int ldap_count_references( LDAP *ld, LDAPMessage *res );
2674 ld The session handle.
2676 res The search result, as obtained by a call to one of the synchro-
2677 nous search routines or ldap_result().
2679 entry The entry returned by a previous call to ldap_first_entry() or
2682 ref The reference returned by a previous call to
2683 ldap_first_reference() or ldap_next_reference().
2685 ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and
2686 ldap_next_reference() all return NULL when no more entries or references
2690 Expires: 23 August 1999 [Page 48]
2692 C LDAP API C LDAP Application Program Interface 23 February 1999
2695 exist in the result set to be returned. NULL is also returned if an
2696 error occurs while stepping through the entries or references, in which
2697 case the error parameters in the session handle ld will be set to indi-
2700 ldap_count_entries() returns the number of entries contained in a chain
2701 of entries. It can also be used to count the number of entries that
2702 remain in a chain if called with a message, entry or reference returned
2703 by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
2704 ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
2706 ldap_count_references() returns the number of references contained in a
2707 chain of search results. It can also be used to count the number of
2708 references that remain in a chain.
2711 15.2. Stepping Through the Attributes of an Entry
2713 The ldap_first_attribute() and ldap_next_attribute() calls are used to
2714 step through the list of attribute types returned with an entry.
2716 char *ldap_first_attribute(
2722 char *ldap_next_attribute(
2728 void ldap_memfree( char *mem );
2732 ld The session handle.
2734 entry The entry whose attributes are to be stepped through, as returned
2735 by ldap_first_entry() or ldap_next_entry().
2737 ptr In ldap_first_attribute(), the address of a pointer used inter-
2738 nally to keep track of the current position in the entry. In
2739 ldap_next_attribute(), the pointer returned by a previous call to
2740 ldap_first_attribute(). The BerElement type itself is an opaque
2741 structure that is described in more detail later in this document
2742 in the section "Encoded ASN.1 Value Manipulation".
2746 Expires: 23 August 1999 [Page 49]
2748 C LDAP API C LDAP Application Program Interface 23 February 1999
2751 mem A pointer to memory allocated by the LDAP library, such as the
2752 attribute type names returned by ldap_first_attribute() and
2753 ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
2754 is NULL, nothing is done.
2756 ldap_first_attribute() and ldap_next_attribute() will return NULL when
2757 the end of the attributes is reached, or if there is an error, in which
2758 case the error parameters in the session handle ld will be set to indi-
2761 Both routines return a pointer to an allocated buffer containing the
2762 current attribute name. This should be freed when no longer in use by
2763 calling ldap_memfree().
2765 ldap_first_attribute() will allocate and return in ptr a pointer to a
2766 BerElement used to keep track of the current position. This pointer
2767 should be passed in subsequent calls to ldap_next_attribute() to step
2768 through the entry's attributes. After a set of calls to
2769 ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it
2770 should be freed by calling ber_free( ptr, 0 ). Note that it is very
2771 important to pass the second parameter as 0 (zero) in this call, since
2772 the buffer associated with the BerElement does not point to separately
2775 The attribute type names returned are suitable for passing in a call to
2776 ldap_get_values() and friends to retrieve the associated values.
2779 15.3. Retrieving the Values of an Attribute
2781 ldap_get_values() and ldap_get_values_len() are used to retrieve the
2782 values of a given attribute from an entry. ldap_count_values() and
2783 ldap_count_values_len() are used to count the returned values.
2784 ldap_value_free() and ldap_value_free_len() are used to free the values.
2786 char **ldap_get_values(
2792 struct berval **ldap_get_values_len(
2798 int ldap_count_values( char **vals );
2802 Expires: 23 August 1999 [Page 50]
2804 C LDAP API C LDAP Application Program Interface 23 February 1999
2807 int ldap_count_values_len( struct berval **vals );
2809 void ldap_value_free( char **vals );
2811 void ldap_value_free_len( struct berval **vals );
2815 ld The session handle.
2817 entry The entry from which to retrieve values, as returned by
2818 ldap_first_entry() or ldap_next_entry().
2820 attr The attribute whose values are to be retrieved, as returned by
2821 ldap_first_attribute() or ldap_next_attribute(), or a caller-
2822 supplied string (e.g., "mail").
2824 vals The values returned by a previous call to ldap_get_values() or
2825 ldap_get_values_len().
2827 Two forms of the various calls are provided. The first form is only
2828 suitable for use with non-binary character string data. The second _len
2829 form is used with any kind of data.
2831 ldap_get_values() and ldap_get_values_len() return NULL if no values are
2832 found for attr or if an error occurs.
2834 ldap_count_values() and ldap_count_values_len() return -1 if an error
2835 occurs such as the vals parameter being invalid.
2837 Note that the values returned are dynamically allocated and should be
2838 freed by calling either ldap_value_free() or ldap_value_free_len() when
2842 15.4. Retrieving the name of an entry
2844 ldap_get_dn() is used to retrieve the name of an entry.
2845 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
2846 into its component parts. ldap_dn2ufn() is used to convert the name into
2847 a more "user friendly" format.
2849 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
2851 char **ldap_explode_dn( const char *dn, int notypes );
2853 char **ldap_explode_rdn( const char *rdn, int notypes );
2858 Expires: 23 August 1999 [Page 51]
2860 C LDAP API C LDAP Application Program Interface 23 February 1999
2863 char *ldap_dn2ufn( const char *dn );
2867 ld The session handle.
2869 entry The entry whose name is to be retrieved, as returned by
2870 ldap_first_entry() or ldap_next_entry().
2872 dn The dn to explode, such as returned by ldap_get_dn().
2874 rdn The rdn to explode, such as returned in the components of the
2875 array returned by ldap_explode_dn().
2877 notypes A boolean parameter, if non-zero indicating that the dn or rdn
2878 components should have their type information stripped off
2879 (i.e., "cn=Babs" would become "Babs").
2881 ldap_get_dn() will return NULL if there is some error parsing the dn,
2882 setting error parameters in the session handle ld to indicate the error.
2883 It returns a pointer to newly allocated space that the caller should
2884 free by calling ldap_memfree() when it is no longer in use. Note the
2885 format of the DNs returned is given by [4].
2887 ldap_explode_dn() returns a NULL-terminated char * array containing the
2888 RDN components of the DN supplied, with or without types as indicated by
2889 the notypes parameter. The components are returned in the order they
2890 appear in the dn. The array returned should be freed when it is no
2891 longer in use by calling ldap_value_free().
2893 ldap_explode_rdn() returns a NULL-terminated char * array containing the
2894 components of the RDN supplied, with or without types as indicated by
2895 the notypes parameter. The components are returned in the order they
2896 appear in the rdn. The array returned should be freed when it is no
2897 longer in use by calling ldap_value_free().
2899 ldap_dn2ufn() converts the DN into the user friendly format described in
2900 [5]. The UFN returned is newly allocated space that should be freed by a
2901 call to ldap_memfree() when no longer in use.
2904 15.5. Retrieving controls from an entry
2906 ldap_get_entry_controls() is used to extract LDAP controls from an
2910 int ldap_get_entry_controls(
2914 Expires: 23 August 1999 [Page 52]
2916 C LDAP API C LDAP Application Program Interface 23 February 1999
2921 LDAPControl ***serverctrlsp
2926 ld The session handle.
2928 entry The entry to extract controls from, as returned by
2929 ldap_first_entry() or ldap_next_entry().
2931 serverctrlsp This result parameter will be filled in with an allocated
2932 array of controls copied out of entry. The control array
2933 should be freed by calling ldap_controls_free(). If ser-
2934 verctrlsp is NULL, no controls are returned.
2936 ldap_get_entry_controls() returns an LDAP error code that indicates
2937 whether the reference could be successfully parsed (LDAP_SUCCESS if all
2942 15.6. Parsing References
2944 ldap_parse_reference() is used to extract referrals and controls from a
2945 SearchResultReference message.
2948 int ldap_parse_reference(
2952 LDAPControl ***serverctrlsp,
2958 ld The session handle.
2960 ref The reference to parse, as returned by ldap_result(),
2961 ldap_first_reference(), or ldap_next_reference().
2963 referralsp This result parameter will be filled in with an allocated
2964 array of character strings. The elements of the array are
2965 the referrals (typically LDAP URLs) contained in ref. The
2966 array should be freed when no longer in used by calling
2970 Expires: 23 August 1999 [Page 53]
2972 C LDAP API C LDAP Application Program Interface 23 February 1999
2975 ldap_value_free(). If referralsp is NULL, the referral
2976 URLs are not returned.
2978 serverctrlsp This result parameter will be filled in with an allocated
2979 array of controls copied out of ref. The control array
2980 should be freed by calling ldap_controls_free(). If ser-
2981 verctrlsp is NULL, no controls are returned.
2983 freeit A boolean that determines whether the ref parameter is
2984 disposed of or not. Pass any non-zero value to have this
2985 routine free ref after extracting the requested informa-
2986 tion. This is provided as a convenience; you can also use
2987 ldap_msgfree() to free the result later.
2989 ldap_parse_reference() returns an LDAP error code that indicates whether
2990 the reference could be successfully parsed (LDAP_SUCCESS if all goes
2994 16. Encoded ASN.1 Value Manipulation
2996 This section describes routines which may be used to encode and decode
2997 BER-encoded ASN.1 values, which are often used inside of control and
3000 With the exceptions of two new functions ber_flatten() and ber_init(),
3001 these functions are compatible with the University of Michigan LDAP 3.3
3002 implementation of BER.
3008 unsigned long bv_len;
3012 A struct berval contains a sequence of bytes and an indication of its
3013 length. The bv_val is not necessarily zero-terminated. bv_len must
3014 always be a nonnegative number. Applications may allocate their own
3017 As defined earlier, the BerElement structure is an opaque structure:
3019 typedef struct berelement BerElement;
3021 It contains not only a copy of the encoded value, but also state infor-
3022 mation used in encoding or decoding. Applications cannot allocate their
3026 Expires: 23 August 1999 [Page 54]
3028 C LDAP API C LDAP Application Program Interface 23 February 1999
3031 own BerElement structures. The internal state is neither thread-
3032 specific nor locked, so two threads should not manipulate the same
3033 BerElement value simultaneously.
3035 A single BerElement value cannot be used for both encoding and decoding.
3037 void ber_bvfree( struct berval *bv );
3039 ber_bvfree() frees a berval returned from this API. Both the bv->bv_val
3040 string and the berval itself are freed. Applications should not use
3041 ber_bvfree() with bervals which the application has allocated.
3043 void ber_bvecfree( struct berval **bv );
3045 ber_bvecfree() frees an array of bervals returned from this API. Each
3046 of the bervals in the array are freed using ber_bvfree(), then the array
3049 struct berval *ber_bvdup( const struct berval *bv );
3051 ber_bvdup() returns a copy of a berval. The bv_val field in the
3052 returned berval points to a different area of memory than the bv_val
3053 field in the argument berval. The NULL pointer is returned on error
3054 (e.g. out of memory).
3056 void ber_free( BerElement *ber, int fbuf );
3058 ber_free() frees a BerElement which is returned from the API calls
3059 ber_alloc_t() or ber_init(). Each BerElement must be freed by the
3060 caller. The second argument fbuf should always be set to 1 to ensure
3061 that the internal buffer used by the BER functions is freed as well as
3062 the BerElement container itself.
3067 BerElement *ber_alloc_t( int options );
3069 ber_alloc_t() constructs and returns BerElement. The NULL pointer is
3070 returned on error. The options field contains a bitwise-or of options
3071 which are to be used when generating the encoding of this BerElement.
3072 One option is defined and must always be supplied:
3074 #define LBER_USE_DER 0x01
3076 When this option is present, lengths will always be encoded in the
3077 minimum number of octets. Note that this option does not cause values
3078 of sets to be rearranged in tag and byte order or default values to be
3082 Expires: 23 August 1999 [Page 55]
3084 C LDAP API C LDAP Application Program Interface 23 February 1999
3087 removed, so these functions are not sufficient for generating DER output
3088 as defined in X.509 and X.680. If the caller takes responsibility for
3089 ordering values of sets correctly and removing default values, DER out-
3090 put as defined in X.509 and X.680 can be produced.
3092 Unrecognized option bits are ignored.
3094 The BerElement returned by ber_alloc_t() is initially empty. Calls to
3095 ber_printf() will append bytes to the end of the ber_alloc_t().
3097 int ber_printf( BerElement *ber, const char *fmt, ... )
3099 The ber_printf() routine is used to encode a BER element in much the
3100 same way that sprintf() works. One important difference, though, is
3101 that state information is kept in the ber argument so that multiple
3102 calls can be made to ber_printf() to append to the end of the BER ele-
3103 ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
3104 ber_printf() interprets and formats its arguments according to the for-
3105 mat string fmt. ber_printf() returns -1 if there is an error during
3106 encoding and a positive number if successful. As with sprintf(), each
3107 character in fmt refers to an argument to ber_printf().
3109 The format string can contain the following format characters:
3111 't' Tag. The next argument is an int specifying the tag to override
3112 the next element to be written to the ber. This works across
3113 calls. The int value must contain the tag class, constructed
3114 bit, and tag value. For example, a tag of "[3]" for a con-
3115 structed type is 0xA3. All implementations must support tags
3116 that fit in a single octet (i.e., where the tag value is less
3117 than 32) and they may support larger tags.
3119 'b' Boolean. The next argument is an int, containing either 0 for
3120 FALSE or 0xff for TRUE. A boolean element is output. If this
3121 format character is not preceded by the 't' format modifier, the
3122 tag 0x01 is used for the element.
3124 'i' Integer. The next argument is an int, containing the integer in
3125 the host's byte order. An integer element is output. If this
3126 format character is not preceded by the 't' format modifier, the
3127 tag 0x02 is used for the element.
3129 'X' Bitstring. The next two arguments are a char * pointer to the
3130 start of the bitstring, followed by an int containing the number
3131 of bits in the bitstring. A bitstring element is output, in
3132 primitive form. If this format character is not preceded by the
3133 't' format modifier, the tag 0x03 is used for the element.
3138 Expires: 23 August 1999 [Page 56]
3140 C LDAP API C LDAP Application Program Interface 23 February 1999
3143 'n' Null. No argument is required. An ASN.1 NULL element is out-
3144 put. If this format character is not preceded by the 't' format
3145 modifier, the tag 0x05 is used for the element.
3147 'o' Octet string. The next two arguments are a char *, followed by
3148 an int with the length of the string. The string may contain
3149 null bytes and need not be zero-terminated. An octet string
3150 element is output, in primitive form. If this format character
3151 is not preceded by the 't' format modifier, the tag 0x04 is used
3154 's' Octet string. The next argument is a char * pointing to a
3155 zero-terminated string. An octet string element in primitive
3156 form is output, which does not include the trailing '\0' (null)
3157 byte. If this format character is not preceded by the 't' format
3158 modifier, the tag 0x04 is used for the element.
3160 'v' Several octet strings. The next argument is a char **, an array
3161 of char * pointers to zero-terminated strings. The last element
3162 in the array must be a NULL pointer. The octet strings do not
3163 include the trailing '\0' (null) byte. Note that a construct
3164 like '{v}' is required to get an actual SEQUENCE OF octet
3165 strings. The 't' format modifier cannot be used with this for-
3168 'V' Several octet strings. A NULL-terminated array of berval *'s is
3169 supplied. Note that a construct like '{V}' is required to get an
3170 actual SEQUENCE OF octet strings. The 't' format modifier cannot
3171 be used with this format character.
3173 '{' Begin sequence. No argument is required. If this format char-
3174 acter is not preceded by the 't' format modifier, the tag 0x30
3177 '}' End sequence. No argument is required. The 't' format modifier
3178 cannot be used with this format character.
3180 '[' Begin set. No argument is required. If this format character
3181 is not preceded by the 't' format modifier, the tag 0x31 is
3184 ']' End set. No argument is required. The 't' format modifier can-
3185 not be used with this format character.
3187 Each use of a '{' format character must be matched by a '}' character,
3188 either later in the format string, or in the format string of a subse-
3189 quent call to ber_printf() for that BerElement. The same applies to the
3190 '[' and ']' format characters.
3194 Expires: 23 August 1999 [Page 57]
3196 C LDAP API C LDAP Application Program Interface 23 February 1999
3199 Sequences and sets nest, and implementations of this API must maintain
3200 internal state to be able to properly calculate the lengths.
3202 int ber_flatten( const BerElement *ber, struct berval **bvPtr );
3204 The ber_flatten routine allocates a struct berval whose contents are a
3205 BER encoding taken from the ber argument. The bvPtr pointer points to
3206 the returned berval, which must be freed using ber_bvfree(). This rou-
3207 tine returns 0 on success and -1 on error.
3209 The ber_flatten API call is not present in U-M LDAP 3.3.
3211 The use of ber_flatten on a BerElement in which all '{' and '}' format
3212 modifiers have not been properly matched is an error (i.e., -1 will be
3213 returned by ber_flatten() if this situation is exists).
3216 16.3. Encoding Example
3218 The following is an example of encoding the following ASN.1 data type:
3220 Example1Request ::= SEQUENCE {
3221 s OCTET STRING, -- must be printable
3223 val2 [0] INTEGER DEFAULT 0
3227 int encode_example1(const char *s,int val1,int val2,struct berval **bvPtr)
3232 ber = ber_alloc_t(LBER_USE_DER);
3234 if (ber == NULL) return -1;
3236 if (ber_printf(ber,"{si",s,val1) == -1) {
3241 if (ber_printf(ber,"ti",0x80,val2) == -1) {
3246 if (ber_printf(ber,"}") == -1) {
3250 Expires: 23 August 1999 [Page 58]
3252 C LDAP API C LDAP Application Program Interface 23 February 1999
3258 rc = ber_flatten(ber,bvPtr);
3268 The following two symbols are available to applications.
3270 #define LBER_ERROR 0xffffffffUL
3271 #define LBER_DEFAULT 0xffffffffUL
3273 BerElement *ber_init( const struct berval *bv );
3275 The ber_init function constructs a BerElement and returns a new BerEle-
3276 ment containing a copy of the data in the bv argument. ber_init returns
3277 the NULL pointer on error.
3279 unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );
3281 The ber_scanf() routine is used to decode a BER element in much the same
3282 way that sscanf() works. One important difference, though, is that some
3283 state information is kept with the ber argument so that multiple calls
3284 can be made to ber_scanf() to sequentially read from the BER element.
3285 The ber argument must be a pointer to a BerElement returned by
3286 ber_init(). ber_scanf interprets the bytes according to the format
3287 string fmt, and stores the results in its additional arguments.
3288 ber_scanf() returns LBER_ERROR on error, and a different value on suc-
3291 The format string contains conversion specifications which are used to
3292 direct the interpretation of the BER element. The format string can
3293 contain the following characters:
3295 'a' Octet string. A char ** argument should be supplied. Memory is
3296 allocated, filled with the contents of the octet string, zero-
3297 terminated, and the pointer to the string is stored in the argu-
3298 ment. The returned value must be freed using ldap_memfree. The
3299 tag of the element must indicate the primitive form (constructed
3300 strings are not supported) but is otherwise ignored and dis-
3301 carded during the decoding. This format cannot be used with
3302 octet strings which could contain null bytes.
3306 Expires: 23 August 1999 [Page 59]
3308 C LDAP API C LDAP Application Program Interface 23 February 1999
3311 'O' Octet string. A struct berval ** argument should be supplied,
3312 which upon return points to an allocated struct berval contain-
3313 ing the octet string and its length. ber_bvfree() must be
3314 called to free the allocated memory. The tag of the element
3315 must indicate the primitive form (constructed strings are not
3316 supported) but is otherwise ignored during the decoding.
3318 'b' Boolean. A pointer to an int should be supplied. The int value
3319 stored will be 0 for FALSE or nonzero for TRUE. The tag of the
3320 element must indicate the primitive form but is otherwise
3321 ignored during the decoding.
3323 'i' Integer. A pointer to an int should be supplied. The int value
3324 stored will be in host byte order. The tag of the element must
3325 indicate the primitive form but is otherwise ignored during the
3326 decoding. ber_scanf() will return an error if the integer can-
3327 not be stored in an int.
3329 'B' Bitstring. A char ** argument should be supplied which will
3330 point to the allocated bits, followed by an unsigned long *
3331 argument, which will point to the length (in bits) of the bit-
3332 string returned. ldap_memfree must be called to free the bit-
3333 string. The tag of the element must indicate the primitive form
3334 (constructed bitstrings are not supported) but is otherwise
3335 ignored during the decoding.
3337 'n' Null. No argument is required. The element is verified to have
3338 a zero-length value and is skipped. The tag is ignored.
3340 'v' Several octet strings. A char *** argument should be supplied,
3341 which upon return points to an allocated NULL-terminated array
3342 of char *'s containing the octet strings. NULL is stored if the
3343 sequence is empty. ldap_memfree must be called to free each
3344 element of the array and the array itself. The tag of the
3345 sequence and of the octet strings are ignored.
3347 'V' Several octet strings (which could contain null bytes). A
3348 struct berval *** should be supplied, which upon return points
3349 to a allocated NULL-terminated array of struct berval *'s con-
3350 taining the octet strings and their lengths. NULL is stored if
3351 the sequence is empty. ber_bvecfree() can be called to free the
3352 allocated memory. The tag of the sequence and of the octet
3353 strings are ignored.
3355 'x' Skip element. The next element is skipped. No argument is
3358 '{' Begin sequence. No argument is required. The initial sequence
3362 Expires: 23 August 1999 [Page 60]
3364 C LDAP API C LDAP Application Program Interface 23 February 1999
3367 tag and length are skipped.
3369 '}' End sequence. No argument is required.
3371 '[' Begin set. No argument is required. The initial set tag and
3374 ']' End set. No argument is required.
3376 unsigned long ber_peek_tag( BerElement *ber, unsigned long *lenPtr );
3378 ber_peek_tag() returns the tag of the next element to be parsed in the
3379 BerElement argument. The length of this element is stored in the
3380 *lenPtr argument. LBER_DEFAULT is returned if there is no further data
3381 to be read. The ber argument is not modified.
3383 unsigned long ber_skip_tag( BerElement *ber, unsigned long *lenPtr );
3385 ber_skip_tag() is similar to ber_peek_tag(), except that the state
3386 pointer in the BerElement argument is advanced past the first tag and
3387 length, and is pointed to the value part of the next element. This rou-
3388 tine should only be used with constructed types and situations when a
3389 BER encoding is used as the value of an OCTET STRING. The length of the
3390 value is stored in *lenPtr.
3392 unsigned long ber_first_element( BerElement *ber,
3393 unsigned long *lenPtr, char **opaquePtr );
3395 unsigned long ber_next_element( BerElement *ber,
3396 unsigned long *lenPtr, char *opaque );
3398 ber_first_element() and ber_next_element() are used to traverse a SET,
3399 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
3400 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
3401 and calls ber_peek_tag() for the first element inside the constructed
3402 value. LBER_DEFAULT is returned if the constructed value is empty.
3403 ber_next_element() positions the state at the start of the next element
3404 in the constructed type. LBER_DEFAULT is returned if there are no
3407 The len and opaque values should not be used by applications other than
3408 as arguments to ber_next_element(), as shown in the example below.
3411 16.5. Decoding Example
3413 The following is an example of decoding an ASN.1 data type:
3418 Expires: 23 August 1999 [Page 61]
3420 C LDAP API C LDAP Application Program Interface 23 February 1999
3423 Example2Request ::= SEQUENCE {
3424 dn OCTET STRING, -- must be printable
3425 scope ENUMERATED { b (0), s (1), w (2) },
3426 ali ENUMERATED { n (0), s (1), f (2), a (3) },
3430 attrs SEQUENCE OF OCTET STRING, -- must be printable
3431 [0] SEQUENCE OF SEQUENCE {
3432 type OCTET STRING -- must be printable,
3433 crit BOOLEAN DEFAULT FALSE,
3437 #define TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */
3439 int decode_example2(struct berval *bv)
3442 unsigned long len, res;
3443 int scope, ali, size, time, tonly;
3444 char *dn = NULL, **attrs = NULL;
3449 fputs("ERROR ber_init failed\n", stderr);
3453 res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali,
3454 &size,&time,&tonly,&attrs);
3456 if (res == LBER_ERROR) {
3457 fputs("ERROR ber_scanf failed\n", stderr);
3465 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
3466 /* *** use attrs[i] */
3467 ldap_memfree(attrs[i]);
3469 ldap_memfree(attrs);
3474 Expires: 23 August 1999 [Page 62]
3476 C LDAP API C LDAP Application Program Interface 23 February 1999
3479 if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
3483 for (tag = ber_first_element(ber,&len,&opaque);
3484 tag != LBER_DEFAULT;
3485 tag = ber_next_element (ber,&len,opaque)) {
3487 unsigned long ttag, tlen;
3490 struct berval *value;
3492 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
3493 fputs("ERROR cannot parse type\n", stderr);
3499 ttag = ber_peek_tag(ber,&tlen);
3500 if (ttag == 0x01) { /* boolean */
3501 if (ber_scanf(ber,"b",
3502 &crit) == LBER_ERROR) {
3503 fputs("ERROR cannot parse crit\n",
3508 } else if (ttag == 0x04) { /* octet string */
3511 fputs("ERROR extra field in controls\n",
3516 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
3517 fputs("ERROR cannot parse value\n", stderr);
3530 Expires: 23 August 1999 [Page 63]
3532 C LDAP API C LDAP Application Program Interface 23 February 1999
3543 17. Security Considerations
3545 LDAPv2 supports security through protocol-level authentication using
3546 clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen-
3547 tication Security Layer) methods. LDAPv3 also supports operation over a
3548 secure transport layer using Transport Layer Security TLS [9]. Readers
3549 are referred to the protocol documents for discussion of related secu-
3550 rity considerations.
3552 Implementations of this API should be cautious when handling authentica-
3553 tion credentials. In particular, keeping long-lived copies of creden-
3554 tials without the application's knowledge is discouraged.
3557 18. Acknowledgements
3559 Many members of the IETF ASID and LDAPEXT working groups as well as
3560 members of the Internet at large have provided useful comments and
3561 suggestions that have been incorporated into this document. Chris
3562 Weider deserves special mention for his contributions as co-author of
3563 earlier revisions of this document.
3565 The original material upon which this specification is based was sup-
3566 ported by the National Science Foundation under Grant No. NCR-9416667.
3571 Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
3573 This document and translations of it may be copied and furnished to oth-
3574 ers, and derivative works that comment on or otherwise explain it or
3575 assist in its implementation may be prepared, copied, published and dis-
3576 tributed, in whole or in part, without restriction of any kind, provided
3577 that the above copyright notice and this paragraph are included on all
3578 such copies and derivative works. However, this document itself may not
3579 be modified in any way, such as by removing the copyright notice or
3580 references to the Internet Society or other Internet organizations,
3581 except as needed for the purpose of developing Internet standards in
3582 which case the procedures for copyrights defined in the Internet
3586 Expires: 23 August 1999 [Page 64]
3588 C LDAP API C LDAP Application Program Interface 23 February 1999
3591 Standards process must be followed, or as required to translate it into
3592 languages other than English.
3594 The limited permissions granted above are perpetual and will not be
3595 revoked by the Internet Society or its successors or assigns.
3597 This document and the information contained herein is provided on an "AS
3598 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
3599 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
3600 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
3601 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
3602 NESS FOR A PARTICULAR PURPOSE.
3607 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
3610 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
3611 "Lightweight Directory Access Protocol (v3): Attribute Syntax
3612 Definitions", RFC 2252, December 1997.
3614 [3] T. Howes, "The String Representation of LDAP Search Filters," RFC
3615 2254, December 1997.
3617 [4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
3618 (v3): A UTF-8 String Representation of Distinguished Names", RFC
3619 2253, December 1997.
3621 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
3622 ing," RFC 1781, March 1995.
3624 [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
3625 (v3)", RFC 2251, December 1997.
3627 [7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control
3628 Extension for Server Side Sorting of Search Results", INTERNET-
3629 DRAFT <draft-ietf-ldapext-sorting-01.txt>, 7 August 1998.
3631 [8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
3634 [9] "Lightweight Directory Access Protocol (v3): Extension for Tran-
3635 sport Layer Security", INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-
3636 tls-04.txt>, November 1998.
3638 [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
3642 Expires: 23 August 1999 [Page 65]
3644 C LDAP API C LDAP Application Program Interface 23 February 1999
3649 [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.
3651 [12] "Character Mnemonics and Character Sets," RFC 1345, June 1992.
3653 [13] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
3656 21. Authors' Addresses
3658 Mark Smith (document editor)
3659 Netscape Communications Corp.
3660 501 E. Middlefield Rd., Mailstop MV068
3661 Mountain View, CA 94043
3667 Netscape Communications Corp.
3668 501 E. Middlefield Rd., Mailstop MV068
3669 Mountain View, CA 94043
3680 andyhe@microsoft.com
3683 Innosoft International, Inc.
3684 8911 Capital of Texas Hwy, Suite 4140
3688 Mark.Wahl@innosoft.com
3698 Expires: 23 August 1999 [Page 66]
3700 C LDAP API C LDAP Application Program Interface 23 February 1999
3704 anoopa@microsoft.com
3707 22. Appendix A - Sample C LDAP API Code
3715 LDAPMessage *res, *e;
3721 /* open an LDAP session */
3722 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
3725 /* authenticate as nobody */
3726 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) {
3727 fprintf( stderr, "ldap_simple_bind_s: %s\n",
3728 ldap_err2string( rc ));
3733 /* search for entries with cn of "Babs Jensen", return all attrs */
3734 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US",
3735 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ))
3737 fprintf( stderr, "ldap_search_s: %s\n",
3738 ldap_err2string( rc ));
3739 if ( res == NULL ) {
3745 /* step through each entry returned */
3746 for ( e = ldap_first_entry( ld, res ); e != NULL;
3747 e = ldap_next_entry( ld, e ) ) {
3748 /* print its name */
3749 dn = ldap_get_dn( ld, e );
3750 printf( "dn: %s\n", dn );
3754 Expires: 23 August 1999 [Page 67]
3756 C LDAP API C LDAP Application Program Interface 23 February 1999
3761 /* print each attribute */
3762 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
3763 a = ldap_next_attribute( ld, e, ptr ) ) {
3764 printf( "\tattribute: %s\n", a );
3766 /* print each value */
3767 vals = ldap_get_values( ld, e, a );
3768 for ( i = 0; vals[i] != NULL; i++ ) {
3769 printf( "\t\tvalue: %s\n", vals[i] );
3771 ldap_value_free( vals );
3774 if ( ptr != NULL ) {
3778 /* free the search results */
3779 ldap_msgfree( res );
3781 /* close and free connection resources */
3788 23. Appendix B - Namespace Consumed By This Specification
3790 The following 2 prefixes are used in this specification to name func-
3795 The following 6 prefixes are used in this specification to name struc-
3796 tures, unions, and typedefs:
3804 The following 3 prefixes are used in this specification to name #defined
3810 Expires: 23 August 1999 [Page 68]
3812 C LDAP API C LDAP Application Program Interface 23 February 1999
3819 24. Appendix C - Summary of Requirements for API Extensions
3821 As the LDAP protocol is extended, this C LDAP API will need to be
3822 extended as well. For example, an LDAPv3 control extension has already
3823 been defined for server-side sorting of search results [7]. This appen-
3824 dix summarizes the requirements for extending this API.
3828 Extensions to this document should not, by default, alter the behavior
3829 of any of the APIs specified in this document. If an extension option-
3830 ally changes the behavior of any existing C LDAP API function calls, the
3831 behavior change must be well documented.
3835 Extensions to this API should follow the general style and naming con-
3836 ventions used in this document. For example, function names should
3837 start with "ldap_" or "ber_" and consist entirely of lowercase letters,
3838 digits, and underscore ('_') characters. More information can be found
3839 in the preceding appendix called "Namespace Consumed By This Specifica-
3842 24.3. Dependence on Externally Defined Types
3844 Extensions to this API should minimize dependencies on types and macros
3845 that are defined in system header files and generally use only intrinsic
3846 types that are part of the C language, types defined in this specifica-
3847 tion, or types defined in the extension document itself.
3849 24.4. Compile Time Information
3851 Extensions to this API should conform to the requirements contained in
3852 the "Retrieving Information at Compile Time" section of this document.
3853 That is, extensions should define a macro of the form:
3855 #define LDAP_API_FEATURE_x level
3857 so that applications can detect the presence or absense of the extension
3858 at compile time and also test the version or level of the extension pro-
3859 vided by an API implementation.
3866 Expires: 23 August 1999 [Page 69]
3868 C LDAP API C LDAP Application Program Interface 23 February 1999
3871 24.5. Runtime Information
3873 Extensions to this API should conform to the requirements contained in
3874 the "Retrieving Information During Execution" section of this document.
3875 That is, each extension should be given a character string name and that
3876 name should appear in the ldapai_extensions array field of the LDAPAPI-
3877 Info structure following a successful call to ldap_get_option() with an
3878 option parameter value of LDAP_OPT_API_INFO. In addition, information
3879 about the extension should be available via a call to ldap_get_option()
3880 with an option parameter value of LDAP_OPT_API_FEATURE_INFO.
3882 24.6. Values Used for Session Handle Options
3884 Extensions to this API that add new session options (for use with the
3885 ldap_get_option() and ldap_set_option() functions) should meet the
3886 requirements contained in the last paragraph of the "LDAP Session Handle
3887 Options" section of this document. Specifically, standards track docu-
3888 ments MUST use values for option macros that are between 0x1000 and
3889 0x3FFF inclusive and private and experimental extensions MUST use values
3890 for the option macros that are between 0x4000 and 0x7FFF inclusive.
3893 25. Appendix D - Known Incompatibilities with RFC 1823
3895 This appendix lists known incompatibilities between this API specifica-
3896 tion and the one contained in RFC 1823, beyond the additional API func-
3897 tions added in support of LDAPv3.
3900 25.1. Opaque LDAP Structure
3902 In RFC 1823, some fields in the LDAP structure were exposed to applica-
3903 tion programmers. To provide a cleaner interface and to make it easier
3904 for implementations to evolve over time without sacrificing binary com-
3905 patibility with older applications, the LDAP structure is now entirely
3906 opaque. The new ldap_set_option() and ldap_get_option() calls can be
3907 used to manipulate per-session and global options.
3910 25.2. Additional Error Codes
3912 The following new error code macros were introduced to support LDAPv3:
3914 LDAP_ADMINLIMIT_EXCEEDED
3915 LDAP_UNAVAILABLE_CRITICAL_EXTENSION
3916 LDAP_CONFIDENTIALITY_REQUIRED
3917 LDAP_SASL_BIND_IN_PROGRESS
3918 LDAP_AFFECTS_MULTIPLE_DSAS
3922 Expires: 23 August 1999 [Page 70]
3924 C LDAP API C LDAP Application Program Interface 23 February 1999
3929 LDAP_CONTROL_NOT_FOUND
3930 LDAP_NO_RESULTS_RETURNED
3931 LDAP_MORE_RESULTS_TO_RETURN
3933 LDAP_REFERRAL_LIMIT_EXCEEDED
3936 25.3. Freeing of String Data with ldap_memfree()
3938 All strings received from the API (e.g., those returned by the
3939 ldap_get_dn() or ldap_dn2ufn() functions) should be freed by calling
3940 ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree()
3944 25.4. Changes to ldap_result()
3946 The meaning of the all parameter to ldap_result has changed slightly.
3947 Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There
3948 is also a new possible value, LDAP_MSG_RECEIVED (0x02).
3950 The result type LDAP_RES_MODDN is now returned where RFC 1823 returned
3951 LDAP_RES_MODRDN. The actual value for these two macros is the same
3955 25.5. Changes to ldap_first_attribute() and ldap_next_attribute
3957 Each non-NULL return value should be freed by calling ldap_memfree()
3958 after use. In RFC 1823, these two functions returned a pointer to a
3959 per-session buffer, which was not very thread-friendly.
3961 After the last call to ldap_first_attribute() or ldap_next_attribute(),
3962 the value set in the ptr parameter should be freed by calling ber_free(
3963 ptr, 0 ). RFC 1823 did not mention that the ptr value should be freed.
3965 The type of the ptr parameter was changed from void * to BerElement *.
3968 25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
3970 In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a
3971 parameter called deleteoldrdn. This does not match the great majority
3972 of implementations, so in this specification the deleteoldrdn parameter
3973 was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional
3974 functions that support deleteoldrdn and are widely implemented as well
3978 Expires: 23 August 1999 [Page 71]
3980 C LDAP API C LDAP Application Program Interface 23 February 1999
3983 were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
3986 25.7. API Specification Clarified
3988 RFC 1823 left many things unspecified, including behavior of various
3989 memory disposal functions when a NULL pointer is presented, requirements
3990 for header files, values of many macros, and so on. This specification
3991 is more complete and generally tighter than the one in RFC 1823.
3994 25.8. Deprecated Functions
3996 A number of functions that are in RFC 1823 are labeled as "deprecated"
3997 in this specification. In most cases, a replacement that provides
3998 equivalent functionality has been defined. The deprecated functions
4002 Use ldap_simple_bind() or ldap_sasl_bind() instead.
4005 Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead.
4007 ldap_kerberos_bind() and ldap_kerberos_bind_s()
4008 No equivalent functions are provided.
4010 ldap_modrdn() and ldap_modrdn2()
4011 Use ldap_rename() instead.
4013 ldap_modrdn_s() and ldap_modrdn2_s()
4014 Use ldap_rename_s() instead.
4017 Use ldap_init() instead.
4020 Use ldap_err2string() instead.
4023 Use ldap_parse_result() instead.
4026 26. Appendix E - Changes Made Since Last Document Revision
4028 The previous version of this document was draft-ietf-ldapext-ldap-c-
4029 api-01.txt, dated 7 August 1998. This appendix lists all of the changes
4030 made to that document to produce the one you are reading now.
4034 Expires: 23 August 1999 [Page 72]
4036 C LDAP API C LDAP Application Program Interface 23 February 1999
4041 General: added the 'const' keyword to function prototypes where
4044 Added two new sections that specify additional features and require-
4045 ments for API implementors:
4046 "Header File Requirements"
4047 "A Client Control That Governs Referral Processing"
4049 "Retrieving Information at Compile Time" section: added
4050 LDAP_VERSION_MIN, LDAP_VERSION_MAX, LDAP_VENDOR_NAME, and
4051 LDAP_VENDOR_VERSION macros. Corrected LDAP_API_VERSION example code
4052 to use >= instead of >. Added note about what value to use for
4053 LDAP_API_VERSION prior to publication of this draft as an RFC (2000 +
4054 draft revision number).
4056 "Retrieving Information During Execution" section: added
4057 LDAP_API_INFO_VERSION macro and clarified the text to explain the
4058 behavior when there is a mismatch between LDAPAPIInfo structure ver-
4059 sions. Added LDAP_OPT_API_FEATURE_INFO to allow applications to
4060 retrieve version information about API extended features.
4062 "LDAP Session Handle Options" section: Added macro definitions for
4063 LDAP_OPT_ON and LDAP_OPT_OFF and changed the "invalue" type for
4064 Boolean options from "int" to "void *". For consistency, we now
4065 require that applications dispose of "char *" and "LDAPControl *"
4066 values that are returned. Added note about which option value ranges
4067 are to be used for various purposes.
4069 "Closing the session" section: added new function ldap_unbind_ext()
4070 to allow controls to be used with unbind operations.
4072 "Searching" section: added requirement that *res be set to NULL by
4073 synchronous calls that fail to return any results.
4075 "Modifying the Name of an Entry" section: added function prototypes
4076 for ldap_modrdn2() and ldap_modrdn2_s() and corrected the ones for
4077 ldap_modrdn() and ldap_modrdn_s() to match the most widely imple-
4080 "Obtaining Results and Peeking Inside LDAP Messages" section: added
4081 requirement that "*res" be set to NULL when ldap_result() fails to
4082 return any results. Added requirement that ldap_msgfree() accept a
4083 NULL "res" parameter.
4085 "Stepping Through the Attributes of an Entry" section: added
4086 requirement that ldap_memfree() accept a NULL "mem" parameter.
4090 Expires: 23 August 1999 [Page 73]
4092 C LDAP API C LDAP Application Program Interface 23 February 1999
4095 "Encoded ASN.1 Value Manipulation - Encoding" section: added note
4096 that implementations may support tags with a value larger than 32
4097 (but this is not required).
4099 "Encoded ASN.1 Value Manipulation - Decoding" section: changed the
4100 LBER_ERROR and LBER_DEFAULT macros to end in "UL" instead of "L"
4101 since all the functions that return these two values return an
4102 "unsigned long" value.
4105 26.2. Editorial changes
4108 Removed section: "Appendix - Outstanding Issues."
4110 Added two new editorial sections:
4111 "Appendix - Summary of Requirements for API Extensions"
4112 "Appendix - Known Incompatibilities with RFC 1823".
4114 General: replaced all occurrences of "LDAP C API" with "C LDAP API"
4117 "Status of Memo" section: added a statement that this document is in
4118 full conformance with all provisions of Section 10 of RFC2026. Also
4119 revised the text about the Internet Draft current and shadow direc-
4120 tories to match the latest I-D guidelines.
4122 Document authors: removed Chris Weider from the list of authors (at
4123 his own request) and added an explicit mention of him in the "Ack-
4124 nowledgements" section. Updated Mark Wahl's company affiliation in
4125 document preface. Added "(document editor)" after Mark Smith's name
4126 in the "Authors' Addresses" section.
4128 Copyright: updated the year to 1999.
4130 "Introduction" section: expanded the sentence that mentioned the sam-
4131 ple code appendix to mention all of the appendices.
4133 "Overview of LDAP API Use" section: numbered the four simple steps
4134 for using the API. Added mention of the referrals client control.
4135 Clarified the text on character sets. Replaced mention of
4136 ldap_bind() with ldap_sasl_bind() because the former is deprecated.
4137 Added note that this API is designed for use in environments where
4138 the 'int' type is at least 32 bits in size.
4140 "Common Data Structures" section: added definition of BerElement so
4141 it is defined before it is used. Added reference back to "Header
4142 File Requirements" for "struct timeval" related considerations.
4146 Expires: 23 August 1999 [Page 74]
4148 C LDAP API C LDAP Application Program Interface 23 February 1999
4151 "Initializing an LDAP Session" section: moved note about ldap_open()
4152 attempting to make a server connection closer to the ldap_open()
4153 function prototype. Added note that using literal IPv6 addresses in
4154 the "hostname" parameter is not yet supported.
4156 "LDAP Session Handle Options" section: replaced one instance of
4157 "Formerly" with "In RFC 1823." Added note about inheritance of
4158 options when automatic referral following is enabled. Added
4159 LDAP_OPT_API_INFO and LDAP_OPT_API_FEATURE_INFO for completeness (not
4160 previously included in this section). Replaced erroneous references
4161 to the "Using Controls" section with references to the "Working With
4162 Controls" section. In the text describing the LDAP_OPT_HOST_NAME
4163 option, added a reference to the "hostname" parameter of ldap_init()
4164 for the syntax of the option value. Clarified that ldap_set_option()
4165 makes a copy of the "invalue" data.
4167 "Working With Controls" section: added a note to remind the reader
4168 that server controls that are marked critical should not be used with
4169 unbind and abandon operations since those two operations have no
4172 "Closing the session" section: made it clear that all open connec-
4173 tions associated with a session handle are closed when any of the
4174 unbind API functions are called.
4176 "Searching" section: added note that only a subset of the filter
4177 functionality is available when communicating with an LDAPv2 server.
4178 Clarified text to explain when a local timeout is used and when it is
4181 "Abandoning An Operation" section: removed some redundant text from
4182 the paragraph that explains the differences between ldap_abandon()
4183 and ldap_abandon_ext().
4185 "Obtaining Results and Peeking Inside LDAP Messages" section: clari-
4186 fied that ldap_result() only returns messages for one request at a
4189 "Handling Errors and Parsing Results" section: replace a few
4190 occurrences of LDAPResult with LDAPMessage (there is no type called
4191 LDAPResult). Changed the names of the "resultoidp" and "resultdatap"
4192 parameters to "retoidp" and "retdatap" to avoid confusion with LDAP
4195 "Stepping Through a List of Entries or References" section: added "or
4196 References" to the section name to better reflect its contents.
4197 Added missing description of "ref" parameter. Added mention of
4198 ldap_first_reference() and ldap_next_reference() in sentence about
4202 Expires: 23 August 1999 [Page 75]
4204 C LDAP API C LDAP Application Program Interface 23 February 1999
4207 function return values.
4209 "Stepping Through the Attributes of an Entry" section: added forward
4210 reference for BerElement type.
4212 "Parsing References" section: in the description of the "ref" parame-
4213 ter, changed the phrase "these routines" to the more accurate "this
4216 "Encoded ASN.1 Value Manipulation - General" section: changed text to
4217 make sense given that the definition of BerElement now appears first
4218 in the "Common Data Structures" section.
4220 "Encoded ASN.1 Value Manipulation - Encoding" section: Changed the
4221 style of function prototypes to better match the rest of the docu-
4222 ment. Corrected a typo in the ber_bvdup() description ("as the"
4223 replaced with "than the"). Changed "null" to "NULL" where appropri-
4224 ate to be consistent with use elsewhere in the document. Removed
4225 mention of sequences from the discussion of the LBER_USE_DER option.
4226 Fixed some truncated sentences (by adding some missing '\' characters
4227 to the nroff document source).
4229 "Encoded ASN.1 Value Manipulation - Encoding Example" section: sim-
4230 plified the error handling in the example code through the use of a
4233 "Encoded ASN.1 Value Manipulation - Decoding" section: Changed the
4234 style of function prototypes to better match the rest of the docu-
4235 ment. Changed "null" to "NULL" and "null-terminated" to "zero-
4236 terminated" where appropriate to be consistent with use elsewhere in
4237 the document. Fixed a typo (the text now says "an allocated" instead
4238 of "a allocated."). Clarified the description of the 'n' format
4239 character for ber_scanf().
4241 "Encoded ASN.1 Value Manipulation - Decoding Example" section:
4242 changed code to not define a macro that begins with "LDAP" since that
4243 prefix is reserved for the API. Removed an extra 'i' from the format
4244 string used in the first call to ber_scanf(). Changed error report-
4245 ing code to send messages to stderr instead of stdout. Changed
4246 declaration of "res" local variable from "int" to "unsigned long" and
4247 corrected one test of the ber_scanf() return value to test against
4248 LBER_ERROR instead of -1. Fixed improperly rendered strings (by
4249 adding '\' characters to the nroff source for this document so that
4250 '\t' and '\n' are correctly rendered).
4252 "Acknowledgements" section: added the mention of Chris Weider.
4253 Rephrased the text that gives credit to the National Science Founda-
4254 tion (it now says "The original material upon which this
4258 Expires: 23 August 1999 [Page 76]
4260 C LDAP API C LDAP Application Program Interface 23 February 1999
4263 specification is based was supported by ..." instead of "This origi-
4264 nal material upon which this revision is based was based upon work
4267 In the "Bibliography" section: Added a reference to RFC 1345 and
4268 ANSI/ISO C. Updated the LDAPv3 TLS and Sorting references to point
4269 to the latest revisions of those documents.
4271 "Appendix - Sample C LDAP API Code": added #include <stdio.h> to the
4272 sample code. Changed the code to demonstrate good error handling by
4273 freeing all memory and calling ldap_unbind() before returning.
4274 Replaced calls to exit() with return statements. Fixed improperly
4275 rendered strings (by adding '\' characters to the nroff source for
4276 this document so that '\t' and '\n' are correctly rendered).
4314 Expires: 23 August 1999 [Page 77]