Network Working Group Timothy A Howes
INTERNET-DRAFT Mark C Smith
OBSOLETES: RFC 1823 Netscape Communications Corp.
The LDAP Application Program Interface
1. Status of this Memo
This draft document will be submitted to the RFC Editor as an informa-
tional document. Distribution of this memo is unlimited. Please send
comments to the authors.
This document is an Internet-Draft. Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups. Note that other groups may also distribute working
documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
2. Introduction
This document defines a C language application program interface to the
lightweight directory access protocol (LDAP). This document replaces the
previous definition of this API, defined in RFC 1823, updating it to
include support for features found in version 3 of the LDAP protocol, as
well as other changes to support information hiding and thread safety.
The LDAP API is designed to be powerful, yet simple to use. It defines
compatible synchronous and asynchronous interfaces to LDAP to suit a
wide variety of applications. This document gives a brief overview of
the LDAP model, then an overview of how the API is used by an applica-
tion program to obtain LDAP information. The API calls are described in
detail, followed by an appendix that provides some example code demon-
strating the use of the API. This document provides information to the
Internet community. It does not specify any standard.
Expires 4/97 [Page 1]
LDAP API October 1996
3. Overview of the LDAP Model
LDAP is the lightweight directory access protocol, described in [2] and
[7]. It can provide a lightweight frontend to the X.500 directory [1],
or a stand-alone service. In either mode, LDAP is based on a client-
server model in which a client makes a TCP connection to an LDAP server,
over which it sends requests and receives responses. LDAPv3 can also be
used over UDP transport.
The LDAP information model is based on the entry, which contains infor-
mation about some object (e.g., a person). Entries are composed of
attributes, which have a type and one or more values. Each attribute has
a syntax that determines what kinds of values are allowed in the attri-
bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
values behave during directory operations (e.g., is case significant
during comparisons).
Entries may be organized in a tree structure, usually based on politi-
cal, geographical, and organizational boundaries. Each entry is uniquely
named relative to its sibling entries by its relative distinguished name
(RDN) consisting of one or more distinguished attribute values from the
entry. At most one value from each attribute may be used in the RDN.
For example, the entry for the person Babs Jensen might be named with
the "Barbara Jensen" value from the commonName attribute.
A globally unique name for an entry, called a distinguished name or DN,
is constructed by concatenating the sequence of RDNs from the entry up
to the root of the tree. For example, if Babs worked for the University
of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
o=University of Michigan, c=US". The DN format used by LDAP is defined
in [4].
Operations are provided to authenticate, search for and retrieve infor-
mation, modify information, and add and delete entries from the tree.
The next sections give an overview of how the API is used and detailed
descriptions of the LDAP API calls that implement all of these func-
tions.
4. Overview of LDAP API Use
An application generally uses the LDAP API in four simple steps.
- Initialize an LDAP session with a default LDAP server. The
ldap_init() call returns a handle to the session, allowing multiple
connections to be open at once.
- Authenticate to the LDAP server. The ldap_bind() call and friends
support a variety of authentication methods.
Expires 4/97 [Page 2]
LDAP API October 1996
- Perform some LDAP operations and obtain some results. ldap_search()
and friends return results which can be parsed by
ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.
- Close the connection. The ldap_unbind() call closes the connection.
Operations can be performed either synchronously or asynchronously. The
names of the synchronous calls end in _s. For example, a synchronous
search can be completed by calling ldap_search_s(). An asynchronous
search can be initiated by calling ldap_search(). All synchronous rou-
tines return an indication of the outcome of the operation (e.g, the
constant LDAP_SUCCESS or some other error code). The asynchronous rou-
tines return the message id of the operation initiated. This id can be
used in subsequent calls to ldap_result() to obtain the result(s) of the
operation. An asynchronous operation can be abandoned by calling
ldap_abandon().
Results and errors are returned in an opaque structure called LDAPMes-
sage. Routines are provided to parse this structure, step through
entries and attributes returned, etc. Routines are also provided to
interpret errors. The next sections describe these routines in more
detail.
5. Calls for performing LDAP operations
This section describes each LDAP operation API call in detail. All calls
take a "connection handle," a pointer to an LDAP structure containing
per-connection information. Many routines return results in an LDAPMes-
sage structure. These structures and others are described as needed
below.
5.1. Initializing an LDAP Session
ldap_init() initializes a session with an LDAP server. The server is not
actually contacted until an operation is performed that requires it,
allowing various options to be set after initialization.
ldap_sslinit() functions the same as ldap_init(), but it also optionally
allows the caller to set up a secure LDAP connection over SSL to the
LDAP server.
typedef struct ldap LDAP;
LDAP *ldap_init( char *hostname, int portno );
LDAP *ldap_sslinit( char *hostname, int portno, int secure );
Use of the following routine is deprecated.
Expires 4/97 [Page 3]
LDAP API October 1996
LDAP *ldap_open( char *hostname, int portno );
Parameters are:
hostname Contains a space-separated list of hostnames or dotted strings
representing the IP address of hosts running an LDAP server to
connect to. The hosts are tried in the order listed, stopping
with the first one to which a successful connection is made.
Note that only ldap_open() attempts to make the connection
before returning to the caller. Neither ldap_init() or
ldap_sslinit() connect to the LDAP server.
portno Contains the TCP or UDP port number to connect to or contact.
The default LDAP port of 389 can be obtained by supplying the
constant LDAP_PORT. The default secure (LDAP over SSL) LDAP
port of 636 can be selected by supplying the constant
LDAPS_PORT.
secure Is non-zero to intialize a secure LDAP session over SSL. If
secure is zero, regular LDAP session will be initialized.
ldap_init(), ldap_sslinit(), and ldap_open() all return a "session han-
dle," a pointer to an opaque structure that should be passed to subse-
quent calls pertaining to the session. These routines return NULL if the
session cannot be initialized.
One of the ldap_bind calls described below must be completed before
other operations can be performed on the session.
The calling program can set various attributes of the session by calling
the routines described in the next section.
5.2. LDAP Session Handle Options
The LDAP session handle returned by ldap_init() and friends is a pointer
to an opaque data type representing an LDAP session. Formerly, this data
type was a structure exposed to the caller, and various fields in the
structure could be set to control aspects of the session, such as size
and time limits on searches.
In the interest of insulating callers from inevitable changes to this
structure, these aspects of the session are now accessed through a pair
of accessor functions, described below.
ldap_get_option() is used to access the current value of various
session-wide parameters. ldap_set_option() is used to set the value of
these parameters.
Expires 4/97 [Page 4]
LDAP API October 1996
int ldap_get_option( LDAP *ld, int option, void *outvalue );
int ldap_set_option( LDAP *ld, int option, void *invalue );
Parameters are:
ld The session handle.
option The name of the option being accessed or set. This parameter
should be one of the following constants, which have the follow-
ing meanings.
LDAP_OPT_DESC
The underlying socket descriptor corresponding to the default
LDAP connection.
LDAP_OPT_DEREF
Controls how aliases are handled during search. It can have
one of the following values: LDAP_DEREF_NEVER,
LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or
LDAP_DEREF_ALWAYS. The LDAP_DEREF_SEARCHING value means
aliases should be dereferenced during the search but not when
locating the base object of the search. The LDAP_DEREF_FINDING
value means aliases should be dereferenced when locating the
base object but not during the search.
LDAP_OPT_SIZELIMIT
A limit on the number of entries to return from a search. A
value of zero means no limit.
LDAP_OPT_TIMELIMIT
A limit on the number of seconds to spend on a search. A value
of zero means no limit
LDAP_OPT_IO_FN_PTRS
See the discussion of I/O environments in Section X.
LDAP_OPT_THREAD_FN_PTRS
See the discussion of threading environments in Section X.
LDAP_OPT_REBIND_FN
See the discussion of ldap_bind() and friends below.
LDAP_OPT_REBIND_ARG
See the discussion of ldap_bind() and friends below.
LDAP_OPT_CACHE_FN_PTRS
See the discussion of LDAP caching in Section X.
Expires 4/97 [Page 5]
LDAP API October 1996
LDAP_OPT_CACHE_STRATEGY
See the discussion of LDAP caching in Section X.
LDAP_OPT_CACHE_ENABLE
See the discussion of LDAP caching in Section X.
LDAP_OPT_REFERRALS
This option controls whether the LDAP library automatically
follows referrals returned by LDAP servers or not. It can be
set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.
LDAP_OPT_SSL
This option controls whether the default LDAP connection is
made secure over SSL or not. It can be set to one of the con-
stants LDAP_OPT_ON or LDAP_OPT_OFF. Note that if
LDAP_OPT_REFERRALS is set to LDAP_OPT_ON and the LDAP library
gets a referral to an SSL LDAP server, it will still do SSL if
possible. This setting has no bearing on connections made when
chasing referrals.
LDAP_OPT_RESTART
This option controls whether LDAP I/O operations should
automatically be restarted if they abort prematurely. It
should be set to one of the constants LDAP_OPT_ON or
LDAP_OPT_OFF. This option is useful if an LDAP I/O operation
may be interrupted prematurely, for example by a timer going
off, or other interrrupt.
LDAP_OPT_VERSION
This option indicates the version of the default LDAP server.
It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3.
LDAP_OPT_SORTKEYS
This option indicates sort keys that should be sent to the
server on subsequent search requests. The value of this option
is a NULL-terminated array of pointers to structures with the
following definition.
struct ldapsortkey {
char *sk_attrtype;
char *sk_matchruleoid;
int sk_reverseorder;
};
outvalue The address of a place to put the value of the option. The
actual type of this parameter depends on the setting of the
option parameter.
Expires 4/97 [Page 6]
LDAP API October 1996
invalue A pointer to the value the option is to be given. The actual
type of this parameter depends on the setting of the option
parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be
given for options that have on or off settings.
5.3. Setting Session Parameters
The ldap_session() and ldap_session_s() calls are used to request that
the LDAP server set certain session parameters. These session parame-
ters are maintained by the server, as opposed to the LDAP * session
parameters described above, which are maintained by the client.
struct ldapsessctl {
char *sc_type;
struct berval sc_value;
int sc_critical;
};
int ldap_session(
LDAP *ld;
struct ldapsessctl **controls;
);
int ldap_session_s(
LDAP *ld;
struct ldapsessctl **controls;
LDAPMessage **result;
);
Parameters are:
ld The session handle.
controls A NULL-terminated array of pointers to ldapsessctl structures
indicating the requested session controls.
result A result parameter that will be filled in with the result of
the session control operation. This parameter is suitable for
passing to ldap_parse_session_result(), described below.
The following constants are defined and may be assigned to the sc_type
field in the ldapsessctl structure. The controls have the following
meanings.
LDAP_SESSION_ATTR_SIZELIMIT
This control sets a limit on the size of any attribute value the
server will return to the client. The sc_value field should point
to a string containing the decimal string representation of the
Expires 4/97 [Page 7]
LDAP API October 1996
size limit in bytes.
LDAP_SESSION_NO_COPY
This control instructs the server not to perform operations against
copies of the data, only to use the master version. It can be set
to LDAP_OPT_ON or LDAP_OPT_OFF.
LDAP_SESSION_PARTIAL_COPY
This control instructs the server that it should return search
results from partial replicas of the directory. It can be set to
LDAP_OPT_ON or LDAP_OPT_OFF.
LDAP_SESSION_REFERRING_SERVER
This control tells the server which server (if any) referred the
client to the server. It is useful in debugging, and should contain
a URL.
LDAP_SESSION_NO_CHAINING
This control instructs the server not to chain requests on the
client's behalf. It should be set to either LDAP_OPT_ON or
LDAP_OPT_OFF.
LDAP_SESSION_SUPPORTED_PROTOCOL
This control instructs the server in which protocols the client
supports for returned referrals. It should be a null-terminated
array of string protocol names, such as "ldap", "cldap", etc.
LDAP_SESSION_ALIAS_ON_UPDATE
This control instructs the server that it should follow aliases on
update (add, delete, modify, modify dn) operations. It should be
set to LDAP_OPT_ON or LDAP_OPT_OFF.
LDAP_SESSION_MANAGE_SERVER
This control instructs the server that the client wants to manage
server data, such as knowledge references, rather than follow the
links they provide. It should be set to LDAP_OPT_ON or
LDAP_OPT_OFF.
LDAP_SESSION_PREFERRED_LANGUAGE
This control tells the server the list of the client's preferred
languages.
ldap_session_s() is synchronous and returns an LDAP error code indicat-
ing the success or failure of the operation.
ldap_session() is asynchronous and returns the message id of the opera-
tion it initiates, or -1 in case of trouble. The result of the operation
may be obtained by a subsequent call to ldap_result().
Expires 4/97 [Page 8]
LDAP API October 1996
5.4. Authenticating to the directory
ldap_bind() and friends are used to authenticate an LDAP client to an
LDAP directory server.
The ldap_extended_bind() and ldap_extended_bind_s() calls can be used to
do general and extensible authentication over LDAP. The routines both
take the dn to bind as, the method to use, as a dotted-string represen-
tation of an OID identifying the method, and a struct berval holding the
credentials. The special constant value LDAP_AUTH_SIMPLE_OID can be
passed to request simple authentication, or the simplified routines
ldap_simple_bind() or ldap_simple_bind_s() can be used.
typedef struct ldapmsg LDAPMessage;
int ldap_extended_bind( LDAP *ld, char *dn, char *methodoid,
struct berval *credentials );
int ldap_extended_bind_s( LDAP *ld, char *dn, char *methodoid,
struct berval *credentials, LDAPMessage **result );
int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );
int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );
The use of the following routines is deprecated:
int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
int ldap_kerberos_bind( LDAP *ld, char *dn );
int ldap_kerberos_bind_s( LDAP *ld, char *dn );
Parameters are:
ld The connection handle.
dn The name of the entry to bind as.
methodoid
Either LDAP_AUTH_SIMPLE_OID, to get simple authentication, or a
dotted text string representing an OID identifying the bind
method.
credentials
The credentials with which to authenticate. Arbitrary credentials
Expires 4/97 [Page 9]
LDAP API October 1996
can be passed using this parameter. The format and content of the
credentials depends on the setting of the methodoid parameter.
result For the synchronous version of extended bind,
ldap_extended_bind_s(), this is a result-parameter that will be
set to the LDAPMessage containing the result of the bind. This
result is suitable for passing to ldap_parse_result() or
ldap_parse_bind_result(), both described below.
passwd For ldap_simple_bind(), the password to compare to the entry's
userPassword attribute.
Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.
Synchronous versions of the routines have names that end in _s. These
routines return the result of the bind operation, either the constant
LDAP_SUCCESS if the operation was successful, or another LDAP error code
if it was not. See the section below on error handling for more informa-
tion about possible errors and how to interpret them.
Asynchronous versions of these routines return the message id of the
bind operation initiated. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the bind. In case of error,
these routines will return -1, setting the session error parameters in
the LDAP structure appropriately.
Note that no other operations over the connection should be attempted
before a bind call has successfully completed. Subsequent bind calls can
be used to re-authenticate over the same connection.
5.5. Closing the connection
ldap_unbind() is used to unbind from the directory, close the connec-
tion, and dispose of the connection handle.
int ldap_unbind( LDAP *ld );
Parameters are:
ld The connection handle.
ldap_unbind() works synchronously, unbinding from the directory, closing
the connection, and freeing up the ld structure before returning.
ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if the
request cannot be sent to the LDAP server). After a call to
ldap_unbind(), the ld connection handle is invalid.
Expires 4/97 [Page 10]
LDAP API October 1996
5.6. Searching
ldap_search() and friends are used to search the LDAP directory, return-
ing a requested set of attributes for each entry matched. There are
three variations.
struct timeval {
long tv_sec;
long tv_usec;
};
int ldap_search(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly
);
int ldap_search_s(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
LDAPMessage **res
);
int ldap_search_st(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
struct timeval *timeout,
LDAPMessage **res
);
Parameters are:
ld The connection handle.
base The dn of the entry at which to start the search.
scope One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or
LDAP_SCOPE_SUBTREE, indicating the scope of the search.
filter A character string as described in RFC 1960 [3], representing
Expires 4/97 [Page 11]
LDAP API October 1996
the search filter.
attrs A NULL-terminated array of strings indicating which attributes
to return for each matching entry. Passing NULL for this
parameter causes all available attributes to be retrieved.
attrsonly A boolean value that should be zero if both attribute types
and values are to be returned, non-zero if only types are
wanted.
timeout For the ldap_search_st() call, this specifies the local search
timeout value.
res For the synchronous calls, this is a result parameter which
will contain the results of the search upon completion of the
call.
There are three options in the ld connection handle which control how
the search is performed. They are:
LDAP_OPT_SIZELIMIT
A limit on the number of entries to return from the search.
A value of zero means no limit.
LDAP_OPT_TIMELIMIT
A limit on the number of seconds to spend on the search. A
value of zero means no limit.
LDAP_OPT_DEREFOne of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying how
aliases should be handled during the search. The
LDAP_DEREF_SEARCHING value means aliases should be derefer-
enced during the search but not when locating the base
object of the search. The LDAP_DEREF_FINDING value means
aliases should be dereferenced when locating the base
object but not during the search.
An asynchronous search is initiated by calling ldap_search(). It returns
the message id of the initiated search. The results of the search can be
obtained by a subsequent call to ldap_result(). The results can be
parsed by the result parsing routines described in detail later. In
case of error, -1 is returned and the session error parameters in the
LDAP structure are set appropriately.
A synchronous search is performed by calling ldap_search_s() or
ldap_search_st(). The routines are identical, except that
ldap_search_st() takes an additional parameter specifying a local
timeout for the search. Both routines return an indication of the
Expires 4/97 [Page 12]
LDAP API October 1996
result of the search, either LDAP_SUCCESS or some error indication (see
Error Handling below). The entries returned from the search (if any)
are contained in the res parameter. This parameter is opaque to the
caller. Entries, attributes, values, etc., should be extracted by cal-
ling the parsing routines described below. The results contained in res
should be freed when no longer in use by calling ldap_msgfree(),
described later.
5.7. Reading an Entry
LDAP does not support a read operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to read,
scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs
contains the list of attributes to return.
5.8. Listing the Children of an Entry
LDAP does not support a list operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to list,
scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)".
attrs contains the list of attributes to return for each child entry.
5.9. Returning Search Results a Page at a Time
New to LDAPv3 is support in the protocol for retrieving search results a
page at a time. The ldap_search_init_page() and ldap_search_get_page()
routines provide an API interface to this capability.
typedef struct ldapsearch LDAPSearch;
LDAPSearch *ldap_search_init_page(
LDAP *ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
struct ldapsortkey **sortkeys
);
int ldap_search_get_page(
LDAP *ld,
LDAPSearch *searchhandle,
int startatentry,
int pagesize,
int *totalcount
);
Expires 4/97 [Page 13]
LDAP API October 1996
int ldap_search_get_page_s(
LDAP *ld,
LDAPSearch *searchhandle,
int startatentry,
int pagesize,
int *totalcount,
LDAPMessage **result
);
int ldap_search_abandon_page(
LDAP *ld,
LDAPSearch *searchhandle
);
The parameters to ldap_search_init_page() are exactly the same as those
to ldap_search(), except for the additional sortkeys parameter. This
parameter and parameters to ldap_search_get_page() are:
ld The connection handle.
sortkeys If the results of the search are desired back in sorted order,
this parameter is a NULL-terminated array of pointers to struct
sortkeys, indicating the attribute types and matching rules by
which the results are to be sorted. If this parameter is NULL,
the default value for sortkeys, if any, is taken from the LDAP
session parameter LDAP_OPT_SORTKEYS.
searchhandle
A handle to an opaque data type returned from a successful call
to ldap_search_init_page(). This parameter should be passed to
all subsequent calls to ldap_search_get_page() or
ldap_search_get_page_s() pertaining to the same search.
startatentry
The number of entries in the search result before which the
page to be retrieved begins. To start at the beginning of the
search result, supply 0 (zero) for startatentry. To begin in
the middle of a 100-entry search result, supply 50 for starta-
tentry.
pagesize The number of entries that should be returned in the page. No
more than this many entries will be returned from the search,
though fewer can be returned if the page extends beyond the
total size of the result set.
totalcount A result-parameter that will be set to the total number of
entries in the search result. This parameter may change on
subsequent calls to ldap_search_get_page() or
Expires 4/97 [Page 14]
LDAP API October 1996
ldap_search_get_page_s(), if the size of the result set
changes (for example, because of additions or deletions to
the directory between calls).
result A result-parameter that will be set to an LDAPMessage contain-
ing the result of the search, which will be either a "page" of
entries, suitable for passing to ldap_first_entry() and friends
(just like a result from ldap_search_s()), or or an LDAPMessage
containing an explanation of an error that occurred, suitable
for passing to ldap_parse_result().
ldap_search_init_page() returns a pointer to an opaque data structure
representing the search, or NULL on error. The non-NULL return value
should be passed to a subsequent call to ldap_search_get_page() or
ldap_search_get_page_s() to retrieve the actual pages of results from
the search.
ldap_search_get_page_s() is synchronous and returns the LDAP error code
resulting from the search operation. This code can be interpreted by
ldap_perror() and friends.
ldap_search_get_page() is asynchronous and returns the message id of the
request it initiates, or -1 on error. The result of the operation can
be obtained by calling ldap_result().
ldap_search_abandon_page() abandons the current search-page sequence
begun by calling ldap_search_init_page(). It frees the searchhandle
structure, which is invalid after the call.
5.10. Comparing a Value Against an Entry
The ldap_compare() and ldap_compare_s() routines are used to compare a
given attribute value assertion against an LDAP entry.
int ldap_compare(
LDAP *ld,
const char *dn,
const char *attr,
struct berval *bvalue
);
int ldap_compare_s(
LDAP *ld,
const char *dn,
const char *attr,
struct berval *bvalue,
char **matchedtype
);
Expires 4/97 [Page 15]
LDAP API October 1996
Parameters are:
ld The connection handle.
dn The name of the entry to compare against.
attr The attribute to compare against.
bvalue The attribute value to compare against those found in the
entry. This parameter is a pointer to a struct berval so it is
possible to compare binary values.
matchedtype
This result-parameter will be set to the attribute type actu-
ally used to match the compare. This is useful if attribute
sub-typing is involved, and the attr given is a parent type. If
no attribute sub-typing is involed (or is not supported, as in
the case of LDAPv2 servers), this result-parameter will be set
to NULL.
5.11. Modifying an entry
The ldap_modify() and ldap_modify_s() routines are used to modify an
existing LDAP entry.
typedef struct ldapmod {
int mod_op;
char *mod_type;
union {
char **modv_strvals;
struct berval **modv_bvals;
} mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvals
int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] );
int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] );
Parameters are:
ld The connection handle;
dn The name of the entry to modify;
mods A NULL-terminated array of modifications to make to the entry.
Expires 4/97 [Page 16]
LDAP API October 1996
The fields in the LDAPMod structure have the following meanings:
mod_op The modification operation to perform. It should be one of
LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This field
also indicates the type of values included in the mod_vals
union. It is ORed with LDAP_MOD_BVALUES to select the
mod_bvalues form. Otherwise, the mod_values form is used.
mod_type The type of the attribute to modify.
mod_vals The values (if any) to add, delete, or replace. Only one of the
mod_values or mod_bvalues variants should be used, selected by
ORing the mod_op field with the constant LDAP_MOD_BVALUES.
mod_values is a NULL-terminated array of zero-terminated
strings and mod_bvalues is a NULL-terminated array of berval
structures that can be used to pass binary values such as
images.
For LDAP_MOD_ADD modifications, the given values are added to the
entry, creating the attribute if necessary. For LDAP_MOD_DELETE
modifications, the given values are deleted from the entry, removing the
attribute if no values remain. If the entire attribute is to be
deleted, the mod_vals field should be set to NULL. For
LDAP_MOD_REPLACE modifications, the attribute will have the listed
values after the modification, having been created if necessary. All
modifications are performed in the order in which they are listed.
ldap_modify_s() is synchronous and returns the LDAP error code resulting
from the modify operation. This code can be interpreted by ldap_perror()
and friends.
ldap_modify() is asynchronous and returns the message id of the request
it initiates, or -1 on error. The result of the operation can be
obtained by calling ldap_result().
5.12. Modifying the Name of an Entry
In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to
change the name of an LDAP entry. They could only be used to change the
least significant component of a name (the RDN or relative distinguished
name). LDAPv3 provides the Modify DN protocol operation that allows more
general name change access. The ldap_moddn() and ldap_moddn_s() routines
are used to change the name of an entry, and the use of the
ldap_modrdn() and ldap_modrdn_s() routines is deprecated.
int ldap_moddn(
LDAP *ld,
char *dn,
Expires 4/97 [Page 17]
LDAP API October 1996
char *newdn,
int deleteoldrdn
);
int ldap_moddn_s(
LDAP *ld,
char *dn,
char *newdn,
int deleteoldrdn
);
Use of the following routines is deprecated.
int ldap_modrdn(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
int ldap_modrdn_s(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
Parameters are:
ld The session handle.
dn The name of the entry whose DN is to be changed.
newdn The new DN to give the entry.
deleteoldrdn
This parameter only has meaning on the modify DN routines if
the newdn has a different RDN than the old DN. It is a boolean
value, if non-zero indicating that the old RDN value(s) should
be removed, if zero indicating that the old RDN value(s) should
be retained as non-distinguished values of the entry.
Parameters of the deprecated routines are not described. Interested
readers are referred to RFC 1823.
The ldap_moddn_s() routine is synchronous, returning the LDAP error code
indicating the outcome of the operation.
The ldap_moddn() routine is asynchronous, returning the message id of
the operation it initiates, or -1 in case of trouble. The result of the
Expires 4/97 [Page 18]
LDAP API October 1996
operation can be obtained by calling ldap_result().
5.13. Adding an entry
ldap_add() and ldap_add_s() are used to add entries to the LDAP direc-
tory.
int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] );
int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] );
Parameters are:
ld The session handle.
dn The name of the entry to add.
attrs The entry's attributes, specified using the LDAPMod structure
defined for ldap_modify(). The mod_type and mod_vals fields should
be filled in. The mod_op field is ignored unless ORed with the
constant LDAP_MOD_BVALUES, used to select the mod_bvalues case of
the mod_vals union.
Note that the parent of the entry must already exist.
ldap_add_s() is synchronous, returning the LDAP error code indicating
the outcome of the operation.
ldap_add() is asynchronous, returning the message id of the operation it
initiates, or -1 in case of trouble. The result of the operation can be
obtained by calling ldap_result().
5.14. Deleting an entry
ldap_delete() and ldap_delete_s() are used to delete entries from the
LDAP directory.
int ldap_delete( LDAP *ld, char *dn );
int ldap_delete_s( LDAP *ld, char *dn );
Parameters are:
ld The session handle.
dn The name of the entry to delete.
Note that the entry to delete must be a leaf entry (i.e., it must have
Expires 4/97 [Page 19]
LDAP API October 1996
no children). Deletion of entire subtrees is not supported by LDAP.
ldap_delete_s() is synchronous, returning the LDAP error code indicating
the outcome of the operation.
ldap_delete() is asynchronous, returning the message id of the operation
it initiates, or -1 in case of trouble. The result of the operation can
be obtained by calling ldap_result().
5.15. Extended Operations
The ldap_extended() and ldap_extended_s() routines allow extended LDAP
operations to be passed to the server, providing a general protocol
extensibility mechanism.
int ldap_extended(
LDAP *ld,
char *requestoid,
struct berval *requestdata
);
int ldap_extended_s(
LDAP *ld,
char *requestoid,
struct berval *requestdata,
LDAPMessage **result
);
Parameters are:
ld The session handle.
requestoidThe dotted-oid text string naming the request.
requestdata
The arbitrary data required by the operation.
result A result parameter that will be filled in with the result of
the operation, suitable for passing to
ldap_parse_extended_result().
The ldap_extended_s() routine is synchronous and returns an LDAP error
code indicating the success or failure of the extended operation.
The ldap_extended() routine is asynchronous and returns the message id
of the operation it initiates, or -1 in case of trouble. The result of
the operation can be obtained by calling ldap_result().
Expires 4/97 [Page 20]
LDAP API October 1996
6. Calls for abandoning an operation
ldap_abandon() is used to abandon an operation in progress.
int ldap_abandon( LDAP *ld, int msgid );
ld The session handle.
msgid The message id of the request to be abandoned.
ldap_abandon() abandons the operation with message id msgid. It returns
zero if the abandon was successful, -1 otherwise. After a successful
call to ldap_abandon(), results with the given message id are never
returned from a call to ldap_result().
7. Calls for obtaining results
ldap_result() is used to obtain the result of a previous asynchronously
initiated operation. ldap_msgfree() frees the results obtained from a
previous call to ldap_result(), or a synchronous search routine.
ldap_msgtype() returns the type of an LDAP message.
int ldap_result(
LDAP *ld,
int msgid,
int all,
struct timeval *timeout,
LDAPMessage **res
);
int ldap_msgfree( LDAPMessage *res );
int ldap_msgtype( LDAPMessage *res );
Parameters are:
ld The connection handle;
msgid The message id of the operation whose results are to be
returned, or the constant LDAP_RES_ANY if any result is
desired;
all A boolean parameter that only has meaning for search results.
If non-zero it indicates that all results of a search should be
retrieved before any are returned. If zero, search results
(entries) will be returned one at a time as they arrive;
Expires 4/97 [Page 21]
LDAP API October 1996
timeout A timeout specifying how long to wait for results to be
returned. A NULL value causes ldap_result() to block until
results are available. A timeout value of zero seconds speci-
fies a polling behavior;
res For ldap_result(), a result parameter that will contain the
result(s) of the operation. For ldap_msgfree(), the result
chain to be freed, obtained from a previous call to
ldap_result(), ldap_search_s(), ldap_search_st(), or
ldap_search_get_page_s().
Upon successful completion, ldap_result() returns the type of the result
returned in the res parameter. This will be one of the following con-
stants.
LDAP_RES_BIND
LDAP_RES_SEARCH_ENTRY
LDAP_RES_SEARCH_REFERENCE -- new
LDAP_RES_SEARCH_RESULT
LDAP_RES_MODIFY
LDAP_RES_ADD
LDAP_RES_DELETE
LDAP_RES_MODRDN
LDAP_RES_COMPARE
LDAP_RES_SESSION -- new
LDAP_RES_EXTENDED -- new
ldap_result() returns 0 if the timeout expired and -1 if an error
occurs, in which case the error parameters of the LDAP session handle
will be set accordingly.
ldap_msgfree() frees the result structure pointed to be res and returns
the type of the message it freed.
ldap_msgtype() returns the type of the LDAP message it is passed as a
parameter. The type will be one of the types listed above, or -1 on
error.
8. Calls for Error and Result Handling
The following calls are used to interpret errors returned by other LDAP
API routines.
int ldap_parse_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
Expires 4/97 [Page 22]
LDAP API October 1996
char ***referrals
);
int ldap_parse_bind_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
char ***referrals,
int *version,
char *serverurl,
struct berval **servercreds
);
int ldap_parse_search_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
char ***referrals,
int *totalcount
);
int ldap_parse_compare_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
char ***referrals,
char **matchedtype
);
int ldap_parse_session_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
char ***referrals,
char ***unsupported
);
int ldap_parse_extended_result(
LDAP *ld,
LDAPMessage *result,
char **matched,
char **errmsg,
char ***referrals,
char **resultoid,
struct berval **resultdata
);
char *ldap_err2string( int err );
Expires 4/97 [Page 23]
LDAP API October 1996
void ldap_perror( LDAP *ld, char *msg );
The use of the following routines is deprecated.
int ldap_result2error(
LDAP *ld,
LDAPMessage *result,
int freeit
);
Parameters are:
ld The connection handle.
result The result of an LDAP operation as returned by ldap_result() or
one of the synchronous API operation calls.
matched In the case of a return of LDAP_NO_SUCH_OBJECT, this result
parameter will be filled in with a DN indicating how much of
the name in the request was recognized. NULL may be passed to
ignore this field.
errmsg This result parameter will be filled in with the contents of
the error message field from the LDAPResult message. NULL may
be passed to ignore this field.
referralsThis result parameter will be filled in with the contents of
the referrals field from the LDAPResult message, indicating
zero or more alternate LDAP servers where the request should be
retried. NULL may be passed to ignore this field.
version For bind results, this result parameter will be filled in with
the version number returned by the LDAP server, indicating the
highest version number the server supports. NULL may be passed
to ignore this field.
serverurlFor bind results, this result parameter will be filled in with
the official LDAP URL for accessing this server, if given. NULL
may be passed to ignore this field.
servercreds
For bind results, this result parameter will be filled in with
the credentials passed back by the server for mutual authenti-
cation, if given. NULL may be passed to ignore this field.
totalcountFor search results, this result parameter will be filled in
with the total count from a paged search request. NULL may be
passed to ignore this field.
Expires 4/97 [Page 24]
LDAP API October 1996
matchedtype
For compare results, this result parameter will be filled in
with the name of the attribute type actually used in the com-
pare match. NULL may be passed to ignore this field.
unsupported
For session results, this result parameter will be filled in with
a NULL-terminated array of string OIDs identifying unsupported
session controls from the corresponding session request. NULL may
be passed to ignore this field.
resultoidFor extended results, this result parameter will be filled in
with the dotted-OID text representation of the name of the
extended operation response. NULL may be passed to ignore this
field.
resultdataFor extended results, this result parameter will be filled in
with a pointer to a struct berval containing the data in the
extended operation response. NULL may be passed to ignore this
field.
err For ldap_err2string(), an LDAP error code, as returned by
ldap_result2error() or one of the synchronous API operation
calls.
msg For ldap_perror(), a message to be displayed before the LDAP
error message.
Parameters for the deprecated calls are not described. Interested
readers are referred to RFC 1823.
All of the ldap_parse*_result() routines return an LDAP error code indi-
cating the outcome of the operation. This is one of the following con-
stants:
LDAP_SUCCESS
LDAP_OPERATIONS_ERROR
LDAP_PROTOCOL_ERROR
LDAP_TIMELIMIT_EXCEEDED
LDAP_SIZELIMIT_EXCEEDED
LDAP_COMPARE_FALSE
LDAP_COMPARE_TRUE
LDAP_STRONG_AUTH_NOT_SUPPORTED
LDAP_STRONG_AUTH_REQUIRED
LDAP_REFERRAL -- new
LDAP_ADMIN_LIMIT_EXCEEDED -- new
LDAP_UNAVAILALBLE_EXTENSION -- new
LDAP_NO_SUCH_ATTRIBUTE
Expires 4/97 [Page 25]
LDAP API October 1996
LDAP_UNDEFINED_TYPE
LDAP_INAPPROPRIATE_MATCHING
LDAP_CONSTRAINT_VIOLATION
LDAP_TYPE_OR_VALUE_EXISTS
LDAP_INVALID_SYNTAX
LDAP_NO_SUCH_OBJECT
LDAP_ALIAS_PROBLEM
LDAP_INVALID_DN_SYNTAX
LDAP_IS_LEAF
LDAP_ALIAS_DEREF_PROBLEM
LDAP_INAPPROPRIATE_AUTH
LDAP_INVALID_CREDENTIALS
LDAP_INSUFFICIENT_ACCESS
LDAP_BUSY
LDAP_UNAVAILABLE
LDAP_UNWILLING_TO_PERFORM
LDAP_LOOP_DETECT
LDAP_NAMING_VIOLATION
LDAP_OBJECT_CLASS_VIOLATION
LDAP_NOT_ALLOWED_ON_NONLEAF
LDAP_NOT_ALLOWED_ON_RDN
LDAP_ALREADY_EXISTS
LDAP_NO_OBJECT_CLASS_MODS
LDAP_RESULTS_TOO_LARGE
LDAP_AFFECTS_MULTIPLE_SERVERS -- new
LDAP_OTHER
LDAP_SERVER_DOWN
LDAP_LOCAL_ERROR
LDAP_ENCODING_ERROR
LDAP_DECODING_ERROR
LDAP_TIMEOUT
LDAP_AUTH_UNKNOWN
LDAP_FILTER_ERROR
LDAP_USER_CANCELLED
LDAP_PARAM_ERROR
LDAP_NO_MEMORY
LDAP_CONNECT_ERROR
In case of trouble (failure to parse the result), -1 is returned.
ldap_err2string() is used to convert a numeric LDAP error code, as
returned by one of the ldap_parse*_result() routines, or one of the syn-
chronous API operation calls, into an informative NULL-terminated char-
acter string message describing the error. It returns a pointer to
static data.
ldap_perror() is used to print the message supplied in msg, followed by
an indication of the error contained in the ld_errno field of the ld
Expires 4/97 [Page 26]
LDAP API October 1996
connection handle, to standard error.
9. Calls for Parsing Search Entries
The following calls are used to parse the entries and references
returned by ldap_search() and friends. These results are returned in an
opaque structure that should only be accessed by calling the routines
described below. Routines are provided to step through the entries and
references returned, step through the attributes of an entry, retrieve
the name of an entry, and retrieve the values associated with a given
attribute in an entry.
9.1. Stepping Through a Set of Entries
The ldap_first_entry() and ldap_next_entry() routines are used to step
through a set of entries and references in a search result.
ldap_count_entries() is used to count the number of entries returned.
ldap_count_references() is used to count the number of references
returned. ldap_msgtype(), described above, can be used to distinguish
between entries and references.
LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
int ldap_count_entries( LDAP *ld, LDAPMessage *res );
int ldap_count_references( LDAP *ld, LDAPMessage *res );
Parameters are:
ld The connection handle;
res The search result, as obtained by a call to one of the synchro-
nous search routines or ldap_result();
entry The entry returned by a previous call to ldap_first_entry() or
ldap_next_entry().
ldap_first_entry() and ldap_next_entry() will return NULL when no more
entries or references exist in the result set to be returned. NULL is
also returned if an error occurs while stepping through the entries, in
which case the error parameters in the ld session handle will be set to
indicate the error.
ldap_count_entries() returns the number of entries contained in a chain
of entries. It can also be used to count the number of entries that
remain in a chain if called with an entry or reference returned by
Expires 4/97 [Page 27]
LDAP API October 1996
ldap_first_entry() or ldap_next_entry().
ldap_count_refernces() returns the number of references contained in a
chain of search results. It can also be used to count the number of
references that remain in a chain if called with an entry or references
returned by ldap_first_entry() or ldap_next_entry().
9.2. Stepping Through the Attributes of an Entry
The ldap_first_attribute() and ldap_next_attribute() calls are used to
step through the list of attribute types returned with an entry.
char *ldap_first_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement **ptr
);
char *ldap_next_attribute(
LDAP *ld,
LDAPMessage *entry,
BerElement *ptr
);
void ldap_memfree( char *mem );
Parameters are:
ld The connection handle;
entry The entry whose attributes are to be stepped through, as returned
by ldap_first_entry() or ldap_next_entry();
ptr In ldap_first_attribute(), the address of a pointer used inter-
nally to keep track of the current position in the entry. In
ldap_next_attribute(), the pointer returned by a previous call to
ldap_first_attribute().
mem A pointer to memory allocated by the LDAP library, such as the
attribute names returned by ldap_first_attribute() and
ldap_next_attribute, or the DN returned by ldap_get_dn().
ldap_first_attribute() and ldap_next_attribute() will return NULL when
the end of the attributes is reached, or if there is an error, in which
case the error parameters in the ld session handle will be set to indi-
cate the error.
Both routines return a pointer to an allocated buffer containing the
Expires 4/97 [Page 28]
LDAP API October 1996
current attribute name. This should be freed when no longer in use by
calling ldap_memfree().
ldap_first_attribute() will allocate and return in ptr a pointer to a
BerElement used to keep track of the current position. This pointer
should be passed in subsequent calls to ldap_next_attribute() to step
through the entry's attributes. After a set of calls to
ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it
should be freed by calling ber_free( ptr, 0 ). Note that it is very
important to pass the second parameter as 0 (zero) in this call.
The attribute names returned are suitable for passing in a call to
ldap_get_values() and friends to retrieve the associated values.
9.3. Retrieving the Values of an Attribute
ldap_get_values() and ldap_get_values_len() are used to retrieve the
values of a given attribute from an entry. ldap_count_values() and
ldap_count_values_len() are used to count the returned values.
ldap_value_free() and ldap_value_free_len() are used to free the values.
typedef struct berval {
unsigned long bv_len;
char *bv_val;
};
char **ldap_get_values(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
struct berval **ldap_get_values_len(
LDAP *ld,
LDAPMessage *entry,
char *attr
);
int ldap_count_values( char **vals );
int ldap_count_values_len( struct berval **vals );
int ldap_value_free( char **vals );
int ldap_value_free_len( struct berval **vals );
Parameters are:
Expires 4/97 [Page 29]
LDAP API October 1996
ld The connection handle.
entry The entry from which to retrieve values, as returned by
ldap_first_entry() or ldap_next_entry().
attr The attribute whose values are to be retrieved, as returned by
ldap_first_attribute() or ldap_next_attribute(), or a caller-
supplied string (e.g., "mail").
vals The values returned by a previous call to ldap_get_values() or
ldap_get_values_len().
Two forms of the various calls are provided. The first form is only
suitable for use with non-binary character string data only. The second
_len form is used with any kind of data.
Note that the values returned are dynamically allocated and should be
freed by calling either ldap_value_free() or ldap_value_free_len() when
no longer in use.
9.4. Retrieving the name of an entry
ldap_get_dn() is used to retrieve the name of an entry.
ldap_explode_dn() is used to break up the name into its component parts.
ldap_dn2ufn() is used to convert the name into a more "user friendly"
format.
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
char **ldap_explode_dn( char *dn, int notypes );
char **ldap_explode_rdn( char *rdn, int notypes );
char *ldap_dn2ufn( char *dn );
Parameters are:
ld The connection handle.
entry The entry whose name is to be retrieved, as returned by
ldap_first_entry() or ldap_next_entry().
dn The dn to explode, such as returned by ldap_get_dn().
rdn The rdn to explode, such as returned in the components of the
array returned by ldap_explode_dn().
notypes A boolean parameter, if non-zero indicating that the dn or rdn
Expires 4/97 [Page 30]
LDAP API October 1996
components should have their type information stripped off
(i.e., "cn=Babs" would become "Babs").
ldap_get_dn() will return NULL if there is some error parsing the dn,
setting error parameters in the ld session handle to indicate the error.
It returns a pointer to malloc'ed space that the caller should free by
calling free() when it is no longer in use. Note the format of the DNs
returned is given by [4].
ldap_explode_dn() returns a NULL-terminated char * array containing the
RDN components of the DN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().
ldap_explode_rdn() returns a NULL-terminated char * array containing the
components of the RDN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().
ldap_dn2ufn() converts the DN into the user friendly format described in
[5]. The UFN returned is malloc'ed space that should be freed by a call
to free() when no longer in use.
10. Security Considerations
LDAP supports security through protocol-level authentication, using
clear-text passwords or other more secure mechanisms. It also supports
running over SSL, which provides strong security at the transport layer.
11. Acknowledgements
Many members of the IETF ASID working group as well as members of the
Internet at large have provided useful comments and suggestions that
have been incorporated into this revision.
This original material upon which this revision is based was based upon
work supported by the National Science Foundation under Grant No. NCR-
9416667.
12. Bibliography
[1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
X.520.
[2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
Access Protocol: Standard and Pilot Attribute Definitions", Inter-
net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996
Expires 4/97 [Page 31]
LDAP API October 1996
[3] T. Howes, "A String Representation of LDAP Search Filters," RFC
1960, June 1996.
[4] S. Kille, "A String Representation of Distinguished Names," RFC
1779, March 1995.
[5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
ing," RFC 1781, March 1995.
[7] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
(v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-03.txt,
October 1996.
13. Author's Addresses
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 415 937-3419
howes@netscape.com
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 313 937-3477
mcs@netscape.com
14. Appendix A - Sample LDAP API Code
#include <ldap.h>
main()
{
LDAP *ld;
LDAPMessage *res, *e;
int i;
char *a, *dn;
BerElement *ptr;
char **vals;
/* open a connection */
if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
exit( 1 );
Expires 4/97 [Page 32]
LDAP API October 1996
/* authenticate as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_simple_bind_s" );
exit( 1 );
}
/* search for entries with cn of "Babs Jensen", return all attrs */
if ( ldap_search_s( ld, "o=University of Michigan, c=US",
LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
!= LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
exit( 1 );
}
/* step through each entry returned */
for ( e = ldap_first_entry( ld, res ); e != NULL;
e = ldap_next_entry( ld, e ) ) {
/* print its name */
dn = ldap_get_dn( ld, e );
printf( "dn: %s\n", dn );
free( dn );
/* print each attribute */
for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
a = ldap_next_attribute( ld, e, ptr ) ) {
printf( "attribute: %s\n", a );
/* print each value */
vals = ldap_get_values( ld, e, a );
for ( i = 0; vals[i] != NULL; i++ ) {
printf( "value: %s\n", vals[i] );
}
ldap_value_free( vals );
}
}
/* free the search results */
ldap_msgfree( res );
/* close and free connection resources */
ldap_unbind( ld );
}
Expires 4/97 [Page 33]