Use the LDAP_SEARCH API for carrying out various LDAP search operations.
#include sys/time.h /* for struct timeval definition */
#include ldap.h
int ldap_search(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char *attrs[],
int attrsonly)
int ldap_search_ext(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char *attrs[],
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
int *msgidp)
int ldap_search_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char *attrs[],
int attrsonly,
LDAPMessage **res)
int ldap_search_ext_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char *attrs[],
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
LDAPMessage **res)
int ldap_search_st(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char *attrs[],
int attrsonly,
struct timeval *timeout,
LDAPMessage **res)filter ::='('filtercomp')'
filtercomp ::= and|or|not|simple
and ::= '&' filterlist
or ::= '|' filterlist
not ::= '!' filter
filterlist ::= filter|filterfiltertype
simple ::= attributetypefiltertype
attributevalue
filtertype ::= '='|'~='|'='|'='For example, the filter "(mail=*)" finds any entries that have a mail attribute. The filter "(mail=*@student.of.life.edu)" finds any entries that have a mail attribute which ends in the specified string. To put parentheses in a filter, escape them with a backslash ( \ ) character. See "RFC 2254, A String Representation of LDAP Search Filters" for a complete description of allowable filters.
See “the Supported special attributes and associated list of operational attributes table” in IBM Security Directory Server Version 6.3.1 Administration Guide. You can know more about the list of specific attributes the server returns for + and ++ attributes.
To know more about the syntax and usage of the command-line utilities, idsldapsearch and ldapsearch, see IBM Security Directory Server Version 6.3.1 Command Reference.
The operation timeout limit relates to the value set in the LDAP handle, ld, by using calls to ldap_set_option (ld, LDAP_OPT_TIMELIMIT, value_in_seconds).
These routines are used to run LDAP search operations.
The ldap_search_ext() API initiates an asynchronous search operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not.
If successful, ldap_search_ext() places the message ID of the request in *msgidp. Use a subsequent call to ldap_result() to obtain the results from the search.
Similar to ldap_search_ext(), the ldap_search() API initiates an asynchronous search operation and returns the message ID of this operation. If an error occurs, ldap_search() returns -1, setting the session error in the LD structure, which can be obtained by using ldap_get_errno(). If successful, use a subsequent call to ldap_result() to obtain the results from the search.
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 an LDAP error code if the operation was not successful. For more information about possible errors and how to interpret them, see LDAP_ERROR. If any entries are returned from the search, they are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, values, and others, must be extracted by calling the result parsing routines. The memory that is allocated for res must be freed when no longer in use, whether the operation was successful, by calling ldap_msgfree().
The ldap_search_ext() and ldap_search_ext_s() APIs support LDAP V3 server controls and client controls, and allow varying size and time limits to be easily specified for each search operation. The ldap_search_st() API is identical to ldap_search_s(), except that it requires an additional parameter that specifies a local timeout for the search.
These options are set and queried by using the ldap_set_option() and ldap_get_option() APIs.
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 that is set to LDAP_SCOPE_BASE, and filter that is set to "(objectclass=*)". The attrs parameter optionally contains the list of attributes to return.
LDAP does not support a list operation directly. Instead, this operation is emulated by a search with base set to the DN of the list entry, scope set to LDAP_SCOPE_ONELEVEL, and filter that is set to "(objectclass=*)". The attrs parameter optionally contains the list of attributes to return for each child entry. If only the distinguished names of child entries are wanted, the attrs parameter must specify a NULL-terminated array of one-character strings that has the value dn.
ldap_search_s(), ldap_search_ext_s, and ldap_search_st() return the LDAP error code from the search operation.
ldap_search() and ldap_search_ext() return -1 instead of a valid msgid if an error occurs, setting the session error in the LD structure. The session error can be obtained by using ldap_get_errno().
For more information, see LDAP_ERROR.
These routines allocate storage that is returned by the res parameter. Use ldap_msgfree() to free this storage.