ldap_search()--Perform an LDAP Search Operation

 #include <ldap.h>

 int ldap_search(
                LDAP        *ld,
                const char  *base,
                int          scope,
                const char  *filter,
                char       **attrs,
                int          attrsonly)

The ldap_search() function is used to perform an LDAP search operation.

ldap_search() is an asynchronous request. A subsequent call to ldap_result() can be used to obtain the results from the search.

Authorities and Locks

No IBM^® i authority is required. All authority checking is done by the LDAP server.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

base

(Input) Specifies the DN of the entry at which to start the search.

scope

(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the base object itself), or LDAP_SCOPE_ONELEVEL (to search the base object's immediate children), or LDAP_SCOPE_SUBTREE (to search the base object and all its descendents).

filter

(Input) Specifies 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 2252, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions." 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=*@student.of.life.edu)" will find any entries that have a mail attribute ending in the specified string.

More complex filters are created using the & and | operators. For example, the filter "(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail attribute. To put parentheses or asterisks in a filter, escape them with a backslash '\' character. See RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of allowable filters.

attrs

(Input) Specifies a null-terminated array of character string attribute types to return from entries that match filter. If NULL is specified, all attributes will be returned.

attrsonly

(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set to 0 to request both attributes types and attribute values.

Return Value

Message ID of the Operation Initiated

if the request was successful. A subsequent call to ldap_result(), can be used to obtain the result.

-1

if the request was not successful.

Error Conditions

If ldap_search() is not successful, -1 will be returned setting the session error(ld_errno) parameters in the LDAP structure appropriately. See LDAP Client API Error Conditions for possible values for the error codes. Use ldap_get_errno() to obtain the error code ld_errno.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_result() -- Retrieve result of an asynchronous LDAP operation.
• ldap_search_s() -- Synchronously search the directory.
• ldap_search_ext() -- Asynchronously search the directory with controls.
• ldap_search_ext_s() -- Synchronously search the directory with controls.
• ldap_search_st() -- Synchronously search the directory with timeout.

[ Back to top | LDAP APIs | APIs by category ]