LDAP_SEARCH(3)                                                                     LDAP_SEARCH(3)



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

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       #include  /* for struct timeval definition */
       #include 

       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 opera-
       tion  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:

                ::= '('  ')'
                ::=  |  |  | 
                ::= '&' 
                ::= '|' 
                ::= '!' 
                ::=  |  
                ::=   
                ::= '=' | '~=' | '<=' | '>='

       The '~=' construct is used  to  specify  approximate  matching.   The  representation  for
         and    are  as  described  in  RFC  2254.   In  addition,
        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 fil-
       ter.  If NULL is specified, the return of all user attributes is requested.  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 fil-
       ter  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  supplied  deallocation  routines.   Return  values  are  contained  in
       .

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.



OpenLDAP 2.2.13                             2004/06/10                             LDAP_SEARCH(3)