ldap_search_ext(3)

     LDAP_SEARCH(3)           OpenLDAP 2.1.12           LDAP_SEARCH(3)

     NAME
          ldap_search, ldap_search_s, ldap_search_st - Perform an LDAP
          search operation

     LIBRARY
          OpenLDAP LDAP (libldap, -lldap)

     SYNOPSIS
          #include <sys/time.h> /* for struct timeval definition */
          #include <ldap.h>

          int ldap_search(ld, base, scope, filter, attrs, attrsonly)
          LDAP *ld;
          char *base;
          int scope;
          char *filter, *attrs[];
          int attrsonly;

          int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
          LDAP *ld;
          char *base;
          int scope;
          char *filter, *attrs[]
          int attrsonly;
          LDAPMessage **res;

          int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
          LDAP *ld;
          char *base;
          int scope;
          char *filter, *attrs[]
          int attrsonly;
          struct timeval *timeout;
          LDAPMessage **res;

     DESCRIPTION
          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 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

     Page 1                                         (printed 1/20/103)

     LDAP_SEARCH(3)           OpenLDAP 2.1.12           LDAP_SEARCH(3)

          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, all attributes will be returned.  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.

     ERRORS
          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.

     NOTES
          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).

     Page 2                                         (printed 1/20/103)

     LDAP_SEARCH(3)           OpenLDAP 2.1.12           LDAP_SEARCH(3)

          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>.

     SEE ALSO
          ldap(3), ldap_result(3), ldap_getfilter(3), ldap_error(3)

     ACKNOWLEDGEMENTS
          OpenLDAP is developed and maintained by The OpenLDAP Project
          (http://www.openldap.org/).  OpenLDAP is derived from
          University of Michigan LDAP 3.3 Release.

     Page 3                                         (printed 1/20/103)