The following functions are used to search the LDAP directory, returning a requested set of attributes for each entry matched. There are five variations.
int ldap_search_ext(
LDAP *ld,
char *base,
int scope,
char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeoutp,
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 *timeoutp,
int sizelimit,
LDAPMessage **res
);
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:
There are three options in the session handle ld which potentially affect how the search is performed. They are:
The ldap_search_ext() function initiates an asynchronous search operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_search_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the results from the search. These results can be parsed using the result parsing routines described in detail later.
Similar to ldap_search_ext(), the ldap_search() function initiates an asynchronous search operation and returns the message id of the operation initiated. As for ldap_search_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the search. In case of error, ldap_search() will return -1, setting the session error parameters in the LDAP structure appropriately.
The synchronous ldap_search_ext_s(), ldap_search_s(), and ldap_search_st() functions all return the result of the 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 information about possible errors and how to interpret them. 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 calling the parsing routines described below. The results contained in res should be freed when no longer in use by calling ldap_msgfree(), described later.
The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 server controls, client controls, and allow varying size and time limits to be easily specified for each search operation. The ldap_search_st() function is identical to ldap_search_s() except that it takes an additional parameter specifying a local timeout for the search.
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.
LDAP does not support a list operation directly. Instead, listing the children of an entry is performed 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.