LDAP_SEARCH(3)						     Library Functions Manual						    LDAP_SEARCH(3)

NAME

       ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s - Perform an LDAP search operation

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

       #include <sys/types.h>
       #include <ldap.h>

       int ldap_search_ext(
	      LDAP *ld,
	      char *base,
	      int scope,
	      char *filter,
	      char *attrs[],
	      int attrsonly,
	      LDAPControl **serverctrls,
	      LDAPControl **clientctrls,
	      struct timeval *timeout,
	      int sizelimit,
	      int *msgidp );

       int ldap_search_ext_s(
	      LDAP *ld,
	      char *base,
	      int scope,
	      char *filter,
	      char *attrs[],
	      int attrsonly,
	      LDAPControl **serverctrls,
	      LDAPControl **clientctrls,
	      struct timeval *timeout,
	      int sizelimit,
	      LDAPMessage **res );

DESCRIPTION

       These  routines	are  used  to  perform	LDAP  search operations.  The ldap_search_ext_s() routine does the search synchronously (i.e., not
       returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the res  parame-
       ter.

       The ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated
       in the integer pointed to by the msgidp parameter.

       The base parameter is the DN of the entry at which to start the search.

       The scope parameter 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, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search
       all of the descendants.	 Note that the latter requires the server support the LDAP Subordinates Search Scope extension.

       The filter is a string representation of the filter to apply in the search.  The string should conform to the format specified in RFC  4515
       as  extended  by RFC 4526.  For instance, "(cn=Jane Doe)".  Note that use of the extension requires the server to support the LDAP Absolute
       True/False Filter extension.  NULL may be specified to indicate the library should send the filter (objectClass=*).

       The attrs parameter is a null-terminated array of attribute descriptions to return from matching entries.  If NULL is specified, the return
       of  all	user  attributes  is  requested.   The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be
       returned.  The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes  to  be  returned.   Note
       that  this  requires  the  server to support the LDAP All Operational Attribute extension.  To request no attributes, the description "1.1"
       (LDAP_NO_ATTRS) should be listed by itself.

       The attrsonly parameter should be set to a non-zero value if only attribute descriptions are wanted.  It should be set to zero (0) if  both
       attributes descriptions and attribute values are wanted.

       The serverctrls and clientctrls parameters may be used to specify server and client controls, respectively.

       The ldap_search_ext_s() routine is the synchronous version of ldap_search_ext().

       It  also  returns  a  code  indicating  success	or,  in  the  case of failure, indicating the nature of the failure of the operation.  See
       ldap_error(3) for details.

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 supplied deallocation routines.
       Return values are contained in <ldap.h>.

DEPRECATED INTERFACES

       The ldap_search() routine is deprecated in favor of the ldap_search_ext() routine.  The ldap_search_s() and ldap_search_st()  routines  are
       deprecated in favor of the ldap_search_ext_s() routine.

       Deprecated  interfaces  generally remain in the library.  The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRE-
       CATED=1) when compiling program designed to use deprecated interfaces.  It is recommended that developers writing new programs, or updating
       old  programs,  avoid use of deprecated interfaces.  Over time, it is expected that documentation (and, eventually, support) for deprecated
       interfaces to be eliminated.

SEE ALSO

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

ACKNOWLEDGEMENTS

       OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.  OpenLDAP Software is derived	from  Uni-
       versity of Michigan LDAP 3.3 Release.

OpenLDAP 2.4.21 						    2009/12/20							    LDAP_SEARCH(3)