ldap_search_st

LDAP_SEARCH(3)                                                  LDAP_SEARCH(3)



NAME
       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
       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 repre-
       sentation  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 '\' char-
       acter.  See RFC 2254 for a more complete description of allowable  fil-
       ters.   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 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  opera-
       tional  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  rou-
       tines,   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 respon-
       sible 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.



OpenLDAP 2.0.27-Release          25 July 1999                   LDAP_SEARCH(3)