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
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
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
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
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
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.
This page is part of the OpenLDAP (an open source implementation of
the Lightweight Directory Access Protocol) project. Information
about the project can be found at ⟨http://www.openldap.org/⟩. If you
have a bug report for this manual page, see
⟨http://www.openldap.org/its/⟩. This page was obtained from the
project's upstream Git repository
⟨git://git.openldap.org/openldap.git⟩ on 2017-03-13. If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page, or
you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
OpenLDAP LDVERSION RELEASEDATE LDAP_SEARCH(3)