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

       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.1.X			  RELEASEDATE			LDAP_SEARCH(3)

Vote for polarhome