ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s -
Perform an LDAP search operation
OpenLDAP LDAP (libldap, -lldap)
#include <sys/types.h>
#include <ldap.h>
int ldap_search_ext(
LDAP * ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
int *msgidp );
int ldap_search_ext_s(
LDAP * ld,
char *base,
int scope,
char *filter,
char *attrs[],
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
LDAPMessage **res );
These routines are used to perform LDAP search operations. The
ldap_search_ext_s() routine does the search synchronously (i.e., not
returning until the operation completes), providing a pointer to the resulting
LDAP messages at the location pointed to by the
res parameter.
The
ldap_search_ext() routine is the asynchronous version, initiating the
search and returning the message id of the operation it initiated in the
integer pointed to by the
msgidp parameter.
The
base parameter is the DN of the entry at which to start the search.
The
scope parameter is the scope of the search and should be one of
LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search
the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and
all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants.
Note that the latter requires the server support the LDAP Subordinates Search
Scope extension.
The
filter is a string representation of the filter to apply in the
search. The string should conform to the format specified in RFC 4515 as
extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use
of the extension requires the server to support the LDAP Absolute True/False
Filter extension. NULL may be specified to indicate the library should send
the filter (objectClass=*).
The
attrs parameter is a null-terminated array of attribute descriptions
to return from matching entries. If NULL is specified, the return of all user
attributes is requested. The description "*"
(LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be
returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may
be used to request all operational attributes to be returned. Note that this
requires the server to support the LDAP All Operational Attribute extension.
To request no attributes, the description "1.1" (LDAP_NO_ATTRS)
should be listed by itself.
The
attrsonly parameter should be set to a non-zero value if only
attribute descriptions are wanted. It should be set to zero (0) if both
attributes descriptions and attribute values are wanted.
The
serverctrls and
clientctrls parameters may be used to specify
server and client controls, respectively.
The
ldap_search_ext_s() routine is the synchronous version of
ldap_search_ext().
It also returns a code indicating success or, in the case of failure, indicating
the nature of the failure of the operation. See
ldap_error(3) for
details.
Note that both read and list functionality are subsumed by these routines, by
using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE
(to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
These routines may dynamically allocate memory. The caller is responsible for
freeing such memory using supplied deallocation routines. Return values are
contained in <ldap.h>.
Note that
res parameter of
ldap_search_ext_s() and
ldap_search_s() should be freed with
ldap_msgfree() regardless
of return value of these functions.
The
ldap_search() routine is deprecated in favor of the
ldap_search_ext() routine. The
ldap_search_s() and
ldap_search_st() routines are deprecated in favor of the
ldap_search_ext_s() routine.
Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED
can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling
program designed to use deprecated interfaces. It is recommended that
developers writing new programs, or updating old programs, avoid use of
deprecated interfaces. Over time, it is expected that documentation (and,
eventually, support) for deprecated interfaces to be eliminated.
ldap(3),
ldap_result(3),
ldap_error(3)
OpenLDAP Software is developed and maintained by The OpenLDAP Project
<
http://www.openldap.org/>.
OpenLDAP Software is derived from the
University of Michigan LDAP 3.3 Release.