These functions are used to perform LDAP search operations. ldap_search_s() does the search synchronously (that is, 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 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 1778. 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 1588 for a more complete description of allowable filters. See ldap_getfilter(3LDAP) for functions to help in constructing search filters automatically.

Attrs is a null-terminated array of attribute types to return from entries that match filter. If NULL is specified, all attributes will be returned. 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.

The ldap_search_ext() function initiates an asynchronous search operation and returns LDAP_SUCCESS if the request was successfully sent to the server, or else it returns a LDAP error code (see ldap_error(3LDAP)). If successful, ldap_search_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(3LDAP), can be used to obtain the result of the add request.

The ldap_search_ext_s() function initiates a synchronous search operation and as such returns the result of the operation itself.

ldap_search_s() and ldap_search_st() will return the LDAP error code resulting from the search operation. See ldap_error(3LDAP) for details.

ldap_search() returns -1 when terminating unsuccessfully.

See attributes(5) for a description of the following attributes:

ldap(3LDAP), ldap_result(3LDAP), ldap_getfilter(3LDAP), ldap_error(3LDAP) , attributes(5)

Note that both read and list functionality are subsumed by these functions, by using a filter like "objectclass=*" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).

These functions may allocate memory which must be freed by the calling application. Return values are contained in <ldap.h>.