ldap_search,  ldap_search_s,  ldap_search_st  - Perform an
       LDAP search operation


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
       specified using a prefix notation according to the follow­
       ing BNF:

               <filter> ::= '(' <filtercomp> ')'
               <filtercomp> ::= <and> | <or> | <not> | <simple>

               <or> ::= '|' <filterlist>
               <not> ::= '!' <filter>
               <filterlist> ::= <filter> | <filter> <filterlist>
               <simple> ::= <attributetype> <filtertype> <attributevalue>
               <filtertype> ::= '=' | '~=' | '<=' | '>='

       The  '~='  construct is used to specify approximate match­
       ing.    The   representation   for   <attributetype>   and
       <attributevalue>  are  as described in RFC 2254.  In addi­
       tion, <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=*@termina­
       tor.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.  See ldap_getfilter(3) for  routines
       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  speci­
       fied,  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_OPERA­
       TIONAL_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).

       These  routines  may  dynamically  allocate  memory.   The
       caller  is  responsible for freeing such memory using sup­
       plied deallocation routines.  Return values are  contained
       in <ldap.h>.

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


ACKNOWLEDGEMENTS

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


Man(1) output converted with man2html