7 Network Working Group T. Howes
8 Request for Comments: 1823 M. Smith
9 Category: Informational University of Michigan
13 The LDAP Application Program Interface
17 This memo provides information for the Internet community. This memo
18 does not specify an Internet standard of any kind. Distribution of
19 this memo is unlimited.
23 This document defines a C language application program interface to
24 the lightweight directory access protocol (LDAP). The LDAP API is
25 designed to be powerful, yet simple to use. It defines compatible
26 synchronous and asynchronous interfaces to LDAP to suit a wide
27 variety of applications. This document gives a brief overview of the
28 LDAP model, then an overview of how the API is used by an application
29 program to obtain LDAP information. The API calls are described in
30 detail, followed by an appendix that provides some example code
31 demonstrating the use of the API.
33 2. Overview of the LDAP Model
35 LDAP is the lightweight directory access protocol, described in [2]
36 and [7]. It can provide a lightweight frontend to the X.500 directory
37 [1], or a stand-alone service. In either mode, LDAP is based on a
38 client-server model in which a client makes a TCP connection to an
39 LDAP server, over which it sends requests and receives responses.
41 The LDAP information model is based on the entry, which contains
42 information about some object (e.g., a person). Entries are composed
43 of attributes, which have a type and one or more values. Each
44 attribute has a syntax that determines what kinds of values are
45 allowed in the attribute (e.g., ASCII characters, a jpeg photograph,
46 etc.) and how those values behave during directory operations (e.g.,
47 is case significant during comparisons).
49 Entries are organized in a tree structure, usually based on
50 political, geographical, and organizational boundaries. Each entry is
51 uniquely named relative to its sibling entries by its relative
52 distinguished name (RDN) consisting of one or more distinguished
53 attribute values from the entry. At most one value from each
54 attribute may be used in the RDN. For example, the entry for the
58 Howes & Smith Informational [Page 1]
60 RFC 1823 LDAP API August 1995
63 person Babs Jensen might be named with the "Barbara Jensen" value
64 from the commonName attribute. A globally unique name for an entry,
65 called a distinguished name or DN, is constructed by concatenating
66 the sequence of RDNs from the root of the tree down to the entry. For
67 example, if Babs worked for the University of Michigan, the DN of her
68 U-M entry might be "cn=Barbara Jensen, o=University of Michigan,
69 c=US". The DN format used by LDAP is defined in [4].
71 Operations are provided to authenticate, search for and retrieve
72 information, modify information, and add and delete entries from the
73 tree. The next sections give an overview of how the API is used and
74 detailed descriptions of the LDAP API calls that implement all of
77 3. Overview of LDAP API Use
79 An application generally uses the LDAP API in four simple steps.
81 o Open a connection to an LDAP server. The ldap_open() call
82 returns a handle to the connection, allowing multiple
83 connections to be open at once.
85 o Authenticate to the LDAP server and/or the X.500 DSA. The
86 ldap_bind() call and friends support a variety of
87 authentication methods.
89 o Perform some LDAP operations and obtain some results.
90 ldap_search() and friends return results which can be parsed
91 by ldap_result2error(), ldap_first_entry(), ldap_next_entry(),
94 o Close the connection. The ldap_unbind() call closes the
97 Operations can be performed either synchronously or asynchronously.
98 Synchronous calls end in _s. For example, a synchronous search can be
99 completed by calling ldap_search_s(). An asynchronous search can be
100 initiated by calling ldap_search(). All synchronous routines return
101 an indication of the outcome of the operation (e.g, the constant
102 LDAP_SUCCESS or some other error code). The asynchronous routines
103 return the message id of the operation initiated. This id can be used
104 in subsequent calls to ldap_result() to obtain the result(s) of the
105 operation. An asynchronous operation can be abandoned by calling
114 Howes & Smith Informational [Page 2]
116 RFC 1823 LDAP API August 1995
119 Results and errors are returned in an opaque structure called
120 LDAPMessage. Routines are provided to parse this structure, step
121 through entries and attributes returned, etc. Routines are also
122 provided to interpret errors. The next sections describe these
123 routines in more detail.
125 4. Calls for performing LDAP operations
127 This section describes each LDAP operation API call in detail. All
128 calls take a "connection handle", a pointer to an LDAP structure
129 containing per-connection information. Many routines return results
130 in an LDAPMessage structure. These structures and others are
131 described as needed below.
133 4.1. Opening a connection
135 ldap_open() opens a connection to the LDAP server.
137 typedef struct ldap {
138 /* ... opaque parameters ... */
145 /* ... opaque parameters ... */
148 LDAP *ldap_open( char *hostname, int portno );
152 hostname Contains a space-separated list of hostnames or dotted
153 strings representing the IP address of hosts running an
154 LDAP server to connect to. The hosts are tried in the
155 order listed, stopping with the first one to which a
156 successful connection is made;
158 portno contains the TCP port number to which to connect. The
159 default LDAP port can be obtained by supplying the
162 ldap_open() returns a "connection handle", a pointer to an LDAP
163 structure that should be passed to subsequent calls pertaining to the
164 connection. It returns NULL if the connection cannot be opened. One
165 of the ldap_bind calls described below must be completed before other
166 operations can be performed on the connection.
170 Howes & Smith Informational [Page 3]
172 RFC 1823 LDAP API August 1995
175 The calling program should assume nothing about the order of the
176 fields in the LDAP structure. There may be other fields in the
177 structure for internal library use. The fields shown above are
178 described as needed in the description of other calls below.
180 4.2. Authenticating to the directory
182 ldap_bind() and friends are used to authenticate to the directory.
184 int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
186 int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
188 int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );
190 int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );
192 int ldap_kerberos_bind( LDAP *ld, char *dn );
194 int ldap_kerberos_bind_s( LDAP *ld, char *dn );
198 ld The connection handle;
200 dn The name of the entry to bind as;
202 cred The credentials with which to authenticate;
204 method One of LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, or
205 LDAP_AUTH_KRBV42, indicating the authentication method to use;
207 passwd For ldap_simple_bind(), the password to compare to the entry's
208 userPassword attribute;
210 There are three types of bind calls, providing simple authentication,
211 kerberos authentication, and general routines to do either one. In
212 the case of Kerberos version 4 authentication using the general
213 ldap_bind() routines, the credentials are ignored, as the routines
214 assume a valid ticket granting ticket already exists which can be
215 used to retrieve the appropriate service tickets.
217 Synchronous versions of the routines have names that end in _s.
218 These routines return the result of the bind operation, either the
219 constant LDAP_SUCCESS if the operation was successful, or another
220 LDAP error code if it was not. See the section below on error
221 handling for more information about possible errors and how to
226 Howes & Smith Informational [Page 4]
228 RFC 1823 LDAP API August 1995
231 Asynchronous versions of these routines return the message id of the
232 bind operation initiated. A subsequent call to ldap_result(),
233 described below, can be used to obtain the result of the bind. In
234 case of error, these routines will return -1, setting the ld_errno
235 field in the LDAP structure appropriately.
237 Note that no other operations over the connection should be attempted
238 before a bind call has successfully completed. Subsequent bind calls
239 can be used to re-authenticate over the same connection.
241 4.3. Closing the connection
243 ldap_unbind() is used to unbind from the directory and close the
246 int ldap_unbind( LDAP *ld );
250 ld The connection handle.
252 ldap_unbind() works synchronously, unbinding from the directory,
253 closing the connection, and freeing up the ld structure before
254 returning. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error
255 code if the request cannot be sent to the LDAP server). After a call
256 to ldap_unbind(), the ld connection handle is invalid.
260 ldap_search() and friends are used to search the LDAP directory,
261 returning a requested set of attributes for each entry matched.
262 There are three variations.
282 Howes & Smith Informational [Page 5]
284 RFC 1823 LDAP API August 1995
300 struct timeval *timeout,
306 ld The connection handle;
308 base The dn of the entry at which to start the search;
310 scope One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or
311 LDAP_SCOPE_SUBTREE, indicating the scope of the search;
313 filter A character string as described in RFC 1558 [3],
314 representing the search filter;
316 attrs A NULL-terminated array of strings indicating which
317 attributes to return for each matching entry. Passing
318 NULL for this parameter causes all available attributes
321 attrsonly A boolean value that should be zero if both attribute
322 types and values are to be returned, non-zero if only
325 timeout For the ldap_search_st() call, this specifies the local
326 search timeout value;
328 res For the synchronous calls, this is a result parameter
329 which will contain the results of the search upon
330 completion of the call.
332 There are three fields in the ld connection handle which control how
333 the search is performed. They are:
338 Howes & Smith Informational [Page 6]
340 RFC 1823 LDAP API August 1995
343 ld_sizelimit A limit on the number of entries to return from the
344 search. A value of zero means no limit;
346 ld_timelimit A limit on the number of seconds to spend on the search.
347 A value of zero means no limit;
349 ld_deref One of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
350 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying
351 how aliases should be handled during the search. The
352 LDAP_DEREF_SEARCHING value means aliases should be
353 dereferenced during the search but not when locating
354 the base object of the search. The LDAP_DEREF_FINDING
355 value means aliases should be dereferenced when
356 locating the base object but not during the search.
358 An asynchronous search is initiated by calling ldap_search(). It
359 returns the message id of the initiated search. The results of the
360 search can be obtained by a subsequent call to ldap_result(). The
361 results can be parsed by the result parsing routines described in
362 detail later. In case of error, -1 is returned and the ld_errno
363 field in the LDAP structure is set appropriately.
365 A synchronous search is performed by calling ldap_search_s() or
366 ldap_search_st(). The routines are identical, except that
367 ldap_search_st() takes an additional parameter specifying a timeout
368 for the search. Both routines return an indication of the result of
369 the search, either LDAP_SUCCESS or some error indication (see Error
370 Handling below). The entries returned from the search (if any) are
371 contained in the res parameter. This parameter is opaque to the
372 caller. Entries, attributes, values, etc., should be extracted by
373 calling the parsing routines described below. The results contained
374 in res should be freed when no longer in use by calling
375 ldap_msgfree(), described later.
377 4.5. Reading an entry
379 LDAP does not support a read operation directly. Instead, this
380 operation is emulated by a search with base set to the DN of the
381 entry to read, scope set to LDAP_SCOPE_BASE, and filter set to
382 "(objectclass=*)". attrs contains the list of attributes to return.
384 4.6. Listing the children of an entry
386 LDAP does not support a list operation directly. Instead, this
387 operation is emulated by a search with base set to the DN of the
388 entry to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set to
389 "(objectclass=*)". attrs contains the list of attributes to return
390 for each child entry.
394 Howes & Smith Informational [Page 7]
396 RFC 1823 LDAP API August 1995
399 4.7. Modifying an entry
401 The ldap_modify() and ldap_modify_s() routines are used to modify an
404 typedef struct ldapmod {
409 struct berval **modv_bvals;
412 #define mod_values mod_vals.modv_strvals
413 #define mod_bvalues mod_vals.modv_bvals
415 int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] );
417 int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] );
421 ld The connection handle;
423 dn The name of the entry to modify;
425 mods A NULL-terminated array of modifications to make to the
428 The fields in the LDAPMod structure have the following meanings:
430 mod_op The modification operation to perform. It should be one of
431 LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This
432 field also indicates the type of values included in the
433 mod_vals union. It is ORed with LDAP_MOD_BVALUES to select
434 the mod_bvalues form. Otherwise, the mod_values form is
437 mod_type The type of the attribute to modify;
439 mod_vals The values (if any) to add, delete, or replace. Only one of
440 the mod_values or mod_bvalues variants should be used,
441 selected by ORing the mod_op field with the constant
442 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
443 zero-terminated strings and mod_bvalues is a NULL-terminated
444 array of berval structures that can be used to pass binary
445 values such as images.
450 Howes & Smith Informational [Page 8]
452 RFC 1823 LDAP API August 1995
455 For LDAP_MOD_ADD modifications, the given values are added to the
456 entry, creating the attribute if necessary. For LDAP_MOD_DELETE
457 modifications, the given values are deleted from the entry, removing
458 the attribute if no values remain. If the entire attribute is to be
459 deleted, the mod_vals field should be set to NULL. For
460 LDAP_MOD_REPLACE modifications, the attribute will have the listed
461 values after the modification, having been created if necessary. All
462 modifications are performed in the order in which they are listed.
464 ldap_modify_s() returns the LDAP error code resulting from the
465 modify operation. This code can be interpreted by ldap_perror()
468 ldap_modify() returns the message id of the request it initiates, or
469 -1 on error. The result of the operation can be obtained by calling
472 4.8. Modifying the RDN of an entry
474 The ldap_modrdn() and ldap_modrdn_s() routines are used to change the
475 name of an LDAP entry.
492 ld The connection handle;
494 dn The name of the entry whose RDN is to be changed;
496 newrdn The new RDN to give the entry;
498 deleteoldrdn A boolean value, if non-zero indicating that the old
499 RDN value(s) should be removed, if zero indicating that
500 the old RDN value(s) should be retained as non-
501 distinguished values of the entry.
506 Howes & Smith Informational [Page 9]
508 RFC 1823 LDAP API August 1995
511 The ldap_modrdn_s() routine is synchronous, returning the LDAP error
512 code indicating the outcome of the operation.
514 The ldap_modrdn() routine is asynchronous, returning the message id
515 of the operation it initiates, or -1 in case of trouble. The result
516 of the operation can be obtained by calling ldap_result().
520 ldap_add() and ldap_add_s() are used to add entries to the LDAP
523 int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] );
525 int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] );
529 ld The connection handle;
531 dn The name of the entry to add;
533 attrs The entry's attributes, specified using the LDAPMod structure
534 defined for ldap_modify(). The mod_type and mod_vals fields
535 should be filled in. The mod_op field is ignored unless ORed
536 with the constant LDAP_MOD_BVALUES, used to select the
537 mod_bvalues case of the mod_vals union.
539 Note that the parent of the entry must already exist.
541 ldap_add_s() is synchronous, returning the LDAP error code indicating
542 the outcome of the operation.
544 ldap_add() is asynchronous, returning the message id of the operation
545 it initiates, or -1 in case of trouble. The result of the operation
546 can be obtained by calling ldap_result().
548 4.10. Deleting an entry
550 ldap_delete() and ldap_delete_s() are used to delete entries from the
553 int ldap_delete( LDAP *ld, char *dn );
555 int ldap_delete_s( LDAP *ld, char *dn );
562 Howes & Smith Informational [Page 10]
564 RFC 1823 LDAP API August 1995
569 ld The connection handle;
571 dn The name of the entry to delete.
573 Note that the entry to delete must be a leaf entry (i.e., it must
574 have no children). Deletion of entire subtrees is not supported by
577 ldap_delete_s() is synchronous, returning the LDAP error code
578 indicating the outcome of the operation.
580 ldap_delete() is asynchronous, returning the message id of the
581 operation it initiates, or -1 in case of trouble. The result of the
582 operation can be obtained by calling ldap_result().
584 5. Calls for abandoning an operation
586 ldap_abandon() is used to abandon an operation in progress.
588 int ldap_abandon( LDAP *ld, int msgid );
590 ldap_abandon() abandons the operation with message id msgid. It
591 returns zero if the abandon was successful, -1 otherwise. After a
592 successful call to ldap_abandon(), results with the given message id
593 are never returned from a call to ldap_result().
595 6. Calls for obtaining results
597 ldap_result() is used to obtain the result of a previous
598 asynchronously initiated operation. ldap_msgfree() frees the results
599 obtained from a previous call to ldap_result(), or a synchronous
606 struct timeval *timeout,
610 int ldap_msgfree( LDAPMessage *res );
618 Howes & Smith Informational [Page 11]
620 RFC 1823 LDAP API August 1995
625 ld The connection handle;
627 msgid The message id of the operation whose results are to be
628 returned, or the constant LDAP_RES_ANY if any result is
631 all A boolean parameter that only has meaning for search
632 results. If non-zero it indicates that all results of a
633 search should be retrieved before any are returned. If zero,
634 search results (entries) will be returned one at a time as
637 timeout A timeout specifying how long to wait for results to be
638 returned. A NULL value causes ldap_result() to block until
639 results are available. A timeout value of zero second
640 specifies a polling behavior;
642 res For ldap_result(), a result parameter that will contain the
643 result(s) of the operation. For ldap_msgfree(), the result
644 chain to be freed, obtained from a previous call to
645 ldap_result() or ldap_search_s() or ldap_search_st().
647 Upon successful completion, ldap_result() returns the type of the
648 result returned in the res parameter. This will be one of the
652 LDAP_RES_SEARCH_ENTRY
653 LDAP_RES_SEARCH_RESULT
660 ldap_result() returns 0 if the timeout expired and -1 if an error
661 occurs, in which case the ld_errno field of the ld structure will be
664 ldap_msgfree() frees the result structure pointed to be res and
665 returns the type of the message it freed.
674 Howes & Smith Informational [Page 12]
676 RFC 1823 LDAP API August 1995
679 7. Calls for error handling
681 The following calls are used to interpret errors returned by other
684 int ldap_result2error(
690 char *ldap_err2string( int err );
692 void ldap_perror( LDAP *ld, char *msg );
696 ld The connection handle;
698 res The result of an LDAP operation as returned by ldap_result()
699 or one of the synchronous API operation calls;
701 freeit A boolean parameter indicating whether the res parameter
702 should be freed (non-zero) or not (zero);
704 err An LDAP error code, as returned by ldap_result2error() or
705 one of the synchronous API operation calls;
707 msg A message to be displayed before the LDAP error message.
709 ldap_result2error() is used to convert the LDAP result message
710 obtained from ldap_result(), or the res parameter returned by one of
711 the synchronous API operation calls, into a numeric LDAP error code.
712 It also parses the ld_matched and ld_error portions of the result
713 message and puts them into the connection handle information. All the
714 synchronous operation routines call ldap_result2error() before
715 returning, ensuring that these fields are set correctly. The relevant
716 fields in the connection structue are:
718 ld_matched In the event of an LDAP_NO_SUCH_OBJECT error return, this
719 parameter contains the extent of the DN matched;
721 ld_error This parameter contains the error message sent in the
722 result by the LDAP server.
724 ld_errno The LDAP error code indicating the outcome of the
725 operation. It is one of the following constants:
730 Howes & Smith Informational [Page 13]
732 RFC 1823 LDAP API August 1995
736 LDAP_OPERATIONS_ERROR
738 LDAP_TIMELIMIT_EXCEEDED
739 LDAP_SIZELIMIT_EXCEEDED
742 LDAP_STRONG_AUTH_NOT_SUPPORTED
743 LDAP_STRONG_AUTH_REQUIRED
744 LDAP_NO_SUCH_ATTRIBUTE
746 LDAP_INAPPROPRIATE_MATCHING
747 LDAP_CONSTRAINT_VIOLATION
748 LDAP_TYPE_OR_VALUE_EXISTS
752 LDAP_INVALID_DN_SYNTAX
754 LDAP_ALIAS_DEREF_PROBLEM
755 LDAP_INAPPROPRIATE_AUTH
756 LDAP_INVALID_CREDENTIALS
757 LDAP_INSUFFICIENT_ACCESS
760 LDAP_UNWILLING_TO_PERFORM
762 LDAP_NAMING_VIOLATION
763 LDAP_OBJECT_CLASS_VIOLATION
764 LDAP_NOT_ALLOWED_ON_NONLEAF
765 LDAP_NOT_ALLOWED_ON_RDN
767 LDAP_NO_OBJECT_CLASS_MODS
768 LDAP_RESULTS_TOO_LARGE
786 Howes & Smith Informational [Page 14]
788 RFC 1823 LDAP API August 1995
791 ldap_err2string() is used to convert a numeric LDAP error code, as
792 returned by ldap_result2error() or one of the synchronous API
793 operation calls, into an informative NULL-terminated character string
794 message describing the error. It returns a pointer to static data.
796 ldap_perror() is used to print the message supplied in msg, followed
797 by an indication of the error contained in the ld_errno field of the
798 ld connection handle, to standard error.
800 8. Calls for parsing search entries
802 The following calls are used to parse the entries returned by
803 ldap_search() and friends. These entries are returned in an opaque
804 structure that should only be accessed by calling the routines
805 described below. Routines are provided to step through the entries
806 returned, step through the attributes of an entry, retrieve the name
807 of an entry, and retrieve the values associated with a given
808 attribute in an entry.
810 8.1. Stepping through a set of entries
812 The ldap_first_entry() and ldap_next_entry() routines are used to
813 step through a set of entries in a search result.
814 ldap_count_entries() is used to count the number of entries returned.
816 LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
818 LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
820 int ldap_count_entries( LDAP *ld, LDAPMessage *res );
824 ld The connection handle;
826 res The search result, as obtained by a call to one of the syn-
827 chronous search routines or ldap_result();
829 entry The entry returned by a previous call to ldap_first_entry() or
832 ldap_first_entry() and ldap_next_entry() will return NULL when no
833 more entries exist to be returned. NULL is also returned if an error
834 occurs while stepping through the entries, in which case the ld_errno
835 field of the ld connection handle will be set to indicate the error.
837 ldap_count_entries() returns the number of entries contained in a
838 chain of entries. It can also be used to count the number of entries
842 Howes & Smith Informational [Page 15]
844 RFC 1823 LDAP API August 1995
847 that remain in a chain if called with an entry returned by
848 ldap_first_entry() or ldap_next_entry().
850 8.2. Stepping through the attributes of an entry
852 The ldap_first_attribute() and ldap_next_attribute() calls are used
853 to step through the list of attribute types returned with an entry.
855 char *ldap_first_attribute(
860 char *ldap_next_attribute(
868 ld The connection handle;
870 entry The entry whose attributes are to be stepped through, as
871 returned by ldap_first_entry() or ldap_next_entry();
873 ptr In ldap_first_attribute(), the address of a pointer used
874 internally to keep track of the current position in the entry.
875 In ldap_next_attribute(), the pointer returned by a previous
876 call to ldap_first_attribute().
878 ldap_first_attribute() and ldap_next_attribute() will return NULL
879 when the end of the attributes is reached, or if there is an error,
880 in which case the ld_errno field in the ld connection handle will be
881 set to indicate the error.
883 Both routines return a pointer to a per-connection buffer containing
884 the current attribute name. This should be treated like static data.
885 ldap_first_attribute() will allocate and return in ptr a pointer to a
886 BerElement used to keep track of the current position. This pointer
887 should be passed in subsequent calls to ldap_next_attribute() to step
888 through the entry's attributes.
890 The attribute names returned are suitable for passing in a call to
891 ldap_get_values() and friends to retrieve the associated values.
898 Howes & Smith Informational [Page 16]
900 RFC 1823 LDAP API August 1995
903 8.3. Retrieving the values of an attribute
905 ldap_get_values() and ldap_get_values_len() are used to retrieve the
906 values of a given attribute from an entry. ldap_count_values() and
907 ldap_count_values_len() are used to count the returned values.
908 ldap_value_free() and ldap_value_free_len() are used to free the
911 typedef struct berval {
912 unsigned long bv_len;
916 char **ldap_get_values(
922 struct berval **ldap_get_values_len(
928 int ldap_count_values( char **vals );
930 int ldap_count_values_len( struct berval **vals );
932 int ldap_value_free( char **vals );
934 int ldap_value_free_len( struct berval **vals );
938 ld The connection handle;
940 entry The entry from which to retrieve values, as returned by
941 ldap_first_entry() or ldap_next_entry();
943 attr The attribute whose values are to be retrieved, as returned by
944 ldap_first_attribute() or ldap_next_attribute(), or a caller-
945 supplied string (e.g., "mail");
947 vals The values returned by a previous call to ldap_get_values() or
948 ldap_get_values_len().
954 Howes & Smith Informational [Page 17]
956 RFC 1823 LDAP API August 1995
959 Two forms of the various calls are provided. The first form is only
960 suitable for use with non-binary character string data only. The
961 second _len form is used with any kind of data.
963 Note that the values returned are malloc'ed and should be freed by
964 calling either ldap_value_free() or ldap_value_free_len() when no
967 8.4. Retrieving the name of an entry
969 ldap_get_dn() is used to retrieve the name of an entry.
970 ldap_explode_dn() is used to break up the name into its component
971 parts. ldap_dn2ufn() is used to convert the name into a more "user
974 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
976 char **ldap_explode_dn( char *dn, int notypes );
978 char *ldap_dn2ufn( char *dn );
982 ld The connection handle;
984 entry The entry whose name is to be retrieved, as returned by
985 ldap_first_entry() or ldap_next_entry();
987 dn The dn to explode, as returned by ldap_get_dn();
989 notypes A boolean parameter, if non-zero indicating that the dn com-
990 ponents should have their type information stripped off
991 (i.e., "cn=Babs" would become "Babs").
993 ldap_get_dn() will return NULL if there is some error parsing the dn,
994 setting ld_errno in the ld connection handle to indicate the error.
995 It returns a pointer to malloc'ed space that the caller should free
996 by calling free() when it is no longer in use. Note the format of
997 the DNs returned is given by [4].
999 ldap_explode_dn() returns a char * array containing the RDN
1000 components of the DN supplied, with or without types as indicated by
1001 the notypes parameter. The array returned should be freed when it is
1002 no longer in use by calling ldap_value_free().
1004 ldap_dn2ufn() converts the DN into the user friendly format described
1005 in [5]. The UFN returned is malloc'ed space that should be freed by a
1006 call to free() when no longer in use.
1010 Howes & Smith Informational [Page 18]
1012 RFC 1823 LDAP API August 1995
1015 9. Security Considerations
1017 LDAP supports minimal security during connection authentication.
1019 10. Acknowledgements
1021 This material is based upon work supported by the National Science
1022 Foundation under Grant No. NCR-9416667.
1026 [1] The Directory: Selected Attribute Syntaxes. CCITT,
1027 Recommendation X.520.
1029 [2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String
1030 Representation of Standard Attribute Syntaxes", University of
1031 Michigan, ISODE Consortium, Performance Systems International,
1032 NeXor Ltd., RFC 1778, March 1995.
1034 [3] Howes, T., "A String Representation of LDAP Search Filters", RFC
1035 1558, University of Michigan, December 1993.
1037 [4] Kille, S., "A String Representation of Distinguished Names", RFC
1038 1779, ISODE Consortium, March 1995.
1040 [5] Kille, S., "Using the OSI Directory to Achieve User Friendly
1041 Naming", RFC 1781, ISODE Consortium, March 1995.
1043 [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer, "Kerberos
1044 Authentication and Authorization System", MIT Project Athena
1045 Documentation Section E.2.1, December 1987
1047 [7] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
1048 Protocol," RFC 1777, Performance Systems International,
1049 University of Michigan, ISODE Consortium, March 1995.
1066 Howes & Smith Informational [Page 19]
1068 RFC 1823 LDAP API August 1995
1071 12. Authors' Addresses
1074 University of Michigan
1075 ITD Research Systems
1077 Ann Arbor, MI 48103-4943
1080 Phone: +1 313 747-4454
1081 EMail: tim@umich.edu
1085 University of Michigan
1086 ITD Research Systems
1088 Ann Arbor, MI 48103-4943
1091 Phone: +1 313 764-2277
1092 EMail: mcs@umich.edu
1122 Howes & Smith Informational [Page 20]
1124 RFC 1823 LDAP API August 1995
1127 13. Appendix A - Sample LDAP API Code
1134 LDAPMessage *res, *e;
1140 /* open a connection */
1141 if ( (ld = ldap_open( "dotted.host.name", LDAP_PORT ))
1145 /* authenticate as nobody */
1146 if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
1147 ldap_perror( ld, "ldap_simple_bind_s" );
1151 /* search for entries with cn of "Babs Jensen",
1153 if ( ldap_search_s( ld, "o=University of Michigan, c=US",
1154 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
1156 ldap_perror( ld, "ldap_search_s" );
1160 /* step through each entry returned */
1161 for ( e = ldap_first_entry( ld, res ); e != NULL;
1162 e = ldap_next_entry( ld, e ) ) {
1163 /* print its name */
1164 dn = ldap_get_dn( ld, e );
1165 printf( "dn: %s0, dn );
1168 /* print each attribute */
1169 for ( a = ldap_first_attribute( ld, e, &ptr );
1171 a = ldap_next_attribute( ld, e, ptr ) ) {
1172 printf( "attribute: %s0, a );
1174 /* print each value */
1178 Howes & Smith Informational [Page 21]
1180 RFC 1823 LDAP API August 1995
1183 vals = ldap_get_values( ld, e, a );
1184 for ( i = 0; vals[i] != NULL; i++ ) {
1185 printf( "value: %s0, vals[i] );
1187 ldap_value_free( vals );
1190 /* free the search results */
1191 ldap_msgfree( res );
1193 /* close and free connection resources */
1234 Howes & Smith Informational [Page 22]