openldap/doc/man/man3/ldap_search.3

.TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation
.SH LIBRARY
OpenLDAP LDAP (libldap, -lldap)
.SH SYNOPSIS
.nf
.ft B
#include <sys/time.h> /* for struct timeval definition */
#include <ldap.h>
.LP
.ft B
int ldap_search(ld, base, scope, filter, attrs, attrsonly)
.ft
LDAP *ld;
char *base;
int scope;
char *filter, *attrs[];
int attrsonly;
.LP
.ft B
int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
.ft
LDAP *ld;
char *base;
int scope;
char *filter, *attrs[]
int attrsonly;
LDAPMessage **res;
.LP
.ft B
int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
.ft
LDAP *ld;
char *base;
int scope;
char *filter, *attrs[]
int attrsonly;
struct timeval *timeout;
LDAPMessage **res;
.LP
.ft B
int ldap_search_ext(ld, base, scope, filter, attrs, attrsonly, serverctrls,
.ft
clientctrls, timeout, sizelimit, msgidp)
.ft
LDAP *ld;
char *base;
int scope;
char *filter, *attrs[]
int attrsonly;
LDAPControl **serverctrls, **clientctrls; 
struct timeval *timeout;
int sizelimit, *msgidp;
.LP
.ft B
int ldap_search_ext_s(ld, base, scope, filter, attrs, attrsonly, serverctrls,
.ft
clientctrls, timeout, sizelimit, res)
.ft
LDAP *ld;
char *base;
int scope;
char *filter, *attrs[]
int attrsonly;
LDAPControl **serverctrls, **clientctrls; 
struct timeval *timeout;
int sizelimit;
LDAPMessage **res;
.SH DESCRIPTION
These routines are used to perform LDAP search operations.
.B ldap_search_s()
does the search synchronously (i.e., not
returning until the operation completes).
.B ldap_search_st()
does
the same, but allows a \fItimeout\fP to be specified.
.B ldap_search()
is the asynchronous version, initiating the search and returning
the message id of the operation it initiated.
\fIBase\fP is the DN of the entry at which to start the search.
\fIScope\fP 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 descendants.
.LP
\fIFilter\fP is a string

representation of the filter to apply in the search.  Simple filters
can be specified as \fI(attributetype=attributevalue)\fP.  More complex
filters are specified using a prefix notation according to the following
BNF:
.LP
.nf
        <filter> ::= '(' <filtercomp> ')'
        <filtercomp> ::= <and> | <or> | <not> | <simple>
        <and> ::= '&' <filterlist>
        <or> ::= '|' <filterlist>
        <not> ::= '!' <filter>
        <filterlist> ::= <filter> | <filter> <filterlist>
        <simple> ::= <attributetype> <filtertype> <attributevalue>
        <filtertype> ::= '=' | '~=' | '<=' | '>='
.fi
.LP
The '~=' construct is used to specify approximate matching.  The
representation for <attributetype> and <attributevalue> are as
described in RFC 4515.  In addition, <attributevalue> can be a single *
to achieve an attribute existence test, or can contain text and *'s
interspersed to achieve substring matching.
.LP
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 4515 for a more complete description of allowable
filters. 
.LP
\fIAttrs\fP is a null-terminated array of attribute types to return
from entries that match \fIfilter\fP.
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 operational attributes to be returned.
To request no attributes, the type "1.1" (LDAP_NO_ATTRS)
should be listed by itself.
.LP
\fIAttrsonly\fP 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.
.LP
.B ldap_search_ext()
routine allows server and client controls to be specified to extend
the search request. This routine is asynchronous like
.BR ldap_search() ,
but its return value is an LDAP error code. It stores the message id
of the request in the integer pointed to
by
.IR msgidp .
.LP
The
.B ldap_search_ext_s()
routine is the synchronous version of
.BR ldap_search_ext().
It also returns an LDAP error code indicating success or failure
of the operation.
.SH ERRORS
.B ldap_search_s()
and
.B ldap_search_st()
will return the LDAP error code resulting from the search operation.
See
.BR ldap_error (3)
for details.
.B ldap_search()
returns -1 in case of trouble.
.LP
.B ldap_search_s(),
.B ldap_search_ext_s
and
.B ldap_search_st()
will return the LDAP error code resulting from the search operation.
See
.BR  ldap_error (3)
for  details.
.B ldap_search()
and
.B ldap_search_ext
returns -1 in case of trouble.
.SH 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).
.LP
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>.
.SH SEE ALSO
.BR ldap (3),
.BR ldap_result (3),
.BR ldap_error (3)
.SH ACKNOWLEDGEMENTS
.B OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.