ldap_search, ldap_search_s, ldap_search_st - Perform an LDAP search operation
#include <sys/time.h> /* for struct timeval definition */
int ldap_search(ld, base, scope, filter, attrs, attrsonly)
char *filter, *attrs;
int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
char *filter, *attrs
int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
char *filter, *attrs
struct timeval *timeout;
These routines are used to perform LDAP search operations. ldap_search_s() does the
search synchronously (i.e., not returning until the operation completes).
ldap_search_st() does the same, but allows a timeout to be specified. ldap_search() is
the asynchronous version, initiating the search and returning the message id of the opera-
tion it initiated. Base is the DN of the entry at which to start the search. Scope 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, or LDAP_SCOPE_SUBTREE, to
search the object and all its descendents.
Filter is a string representation of the filter to apply in the search. Simple filters
can be specified as attributetype=attributevalue. More complex filters are specified
using a prefix notation according to the following BNF:
<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <simple>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<simple> ::= <attributetype> <filtertype> <attributevalue>
<filtertype> ::= '=' | '~=' | '<=' | '>='
The '~=' construct is used to specify approximate matching. The representation for
<attributetype> and <attributevalue> are as described in RFC 2254. In addition,
<attributevalue> can be a single * to achieve an attribute existence test, or can contain
text and *'s interspersed to achieve substring matching.
For example, the filter "mail=*" will find any entries that have a mail attribute. The
filter "email@example.com" will find any entries that have a mail
attribute ending in the specified string. To put parentheses in a filter, escape them
with a backslash '\' character. See RFC 2254 for a more complete description of allowable
filters. See ldap_getfilter(3) for routines to help in constructing search filters auto-
Attrs is a null-terminated array of attribute types to return from entries that match fil-
ter. If NULL is specified, all attributes will be returned. The type "*"
(LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The
type "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational
attributes to be returned. To request no attributes, the type "1.1" (LDAP_NO_ATTRS)
should be listed by itself.
Attrsonly should be set to 1 if only attribute types are wanted. It should be set to 0 if
both attributes types and attribute values are wanted.
ldap_search_s() and ldap_search_st() will return the LDAP error code resulting from the
search operation. See ldap_error(3) for details. ldap_search() returns -1 in case of
Note that both read and list functionality are subsumed by these routines, by using a fil-
ter 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(3), ldap_result(3), ldap_getfilter(3), ldap_error(3)
OpenLDAP is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
OpenLDAP is derived from University of Michigan LDAP 3.3 Release.
OpenLDAP 2.0.27-Release 25 July 1999 LDAP_SEARCH(3)