ldap_search, ldap_search_s, ldap_search_st — Perform an LDAP search operation
#include <sys/time.h> /* for struct timeval definition */ #include <ldap.h>
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) ; |
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 operation 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 descendants.
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 "(mail=*@terminator.rs.itd.umich.edu)" 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.
Attrs
is a
null-terminated array of attribute types to return from
entries that match filter
. If NULL is specified,
the return of all user attributes is requested. 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 trouble.
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>.