LDAP_SEARCH(3)						     Library Functions Manual						    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 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 inter-
       spersed 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.  See ldap_getfilter(3) for  routines	to  help  in  con-
       structing 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_OPERA-
       TIONAL_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  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>.

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)