ldap_search_ext_s

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=attribute-
       value).	 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
       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  speci-
       fied string.  To put parentheses in a filter, escape them with a back-
       slash ’\’ 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, 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 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.2.13			  2004/06/10		       LDAP_SEARCH(3)