openldap/doc/man/man3/ldap_search.3

137 lines
4.3 KiB
Groff
Raw Normal View History

2002-06-13 11:59:10 +08:00
.TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION"
1999-09-12 12:41:47 +08:00
.\" $OpenLDAP$
2007-01-03 04:00:42 +08:00
.\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
1999-09-12 12:41:47 +08:00
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
1998-08-09 08:43:13 +08:00
.SH NAME
ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation
2002-06-21 15:32:54 +08:00
.SH LIBRARY
2002-06-22 05:25:38 +08:00
OpenLDAP LDAP (libldap, -lldap)
1998-08-09 08:43:13 +08:00
.SH SYNOPSIS
.nf
.ft B
2006-06-17 15:06:48 +08:00
#include <sys/types.h>
1998-08-09 08:43:13 +08:00
#include <ldap.h>
.LP
.ft B
2006-06-17 15:06:48 +08:00
int ldap_search_ext(
.RS
LDAP *\fIld\fB,
char *\fIbase\fB,
int \fIscope\fB,
char *\fIfilter\fB,
char *\fIattrs\fB[],
int \fIattrsonly\fB,
LDAPControl **\fIserverctrls\fB,
LDAPControl **\fIclientctrls\fB,
struct timeval *\fItimeout\fB,
int \fIsizelimit\fB,
int *\fImsgidp\fB );
2006-06-17 15:06:48 +08:00
.RE
1998-08-09 08:43:13 +08:00
.LP
.ft B
2006-06-17 15:06:48 +08:00
int ldap_search_ext_s(
.RS
LDAP *\fIld\fB,
char *\fIbase\fB,
int \fIscope\fB,
char *\fIfilter\fB,
char *\fIattrs\fB[],
int \fIattrsonly\fB,
LDAPControl **\fIserverctrls\fB,
LDAPControl **\fIclientctrls\fB,
struct timeval *\fItimeout\fB,
int \fIsizelimit\fB,
2006-06-17 15:06:48 +08:00
LDAPMessage **\fIres\fB );
.RE
1998-08-09 08:43:13 +08:00
.SH DESCRIPTION
These routines are used to perform LDAP search operations.
2006-06-17 15:06:48 +08:00
The
.B ldap_search_ext_s()
routine
1998-08-09 08:43:13 +08:00
does the search synchronously (i.e., not
2006-06-17 15:06:48 +08:00
returning until the operation completes), providing a pointer
to the resulting LDAP messages at the location pointed to by
the \fIres\fP parameter.
1998-08-09 08:43:13 +08:00
.LP
2006-06-17 15:06:48 +08:00
The
.B 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 \fImsgidp\fP parameter.
1998-08-09 08:43:13 +08:00
.LP
2006-06-17 15:06:48 +08:00
The \fIbase\fP parameter is the DN of the entry at which to start the search.
1998-08-09 08:43:13 +08:00
.LP
2006-06-17 15:06:48 +08:00
The \fIscope\fP 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.
1998-08-09 08:43:13 +08:00
.LP
2006-06-17 15:06:48 +08:00
The \fIfilter\fP 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=*).
1998-08-09 08:43:13 +08:00
.LP
2006-06-17 15:06:48 +08:00
The \fIattrs\fP 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.
2006-06-17 15:06:48 +08:00
The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
all user attributes to be returned.
2006-06-17 15:06:48 +08:00
The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to
request all operational attributes to be returned. Note that this
2007-08-07 01:15:25 +08:00
requires the server to support the LDAP All Operational Attribute
2006-06-17 15:06:48 +08:00
extension.
To request no attributes, the description "1.1" (LDAP_NO_ATTRS)
should be listed by itself.
.LP
2006-06-17 15:06:48 +08:00
The \fIattrsonly\fP 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.
.LP
2006-06-17 15:06:48 +08:00
The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used
to specify server and client controls, respectively.
.LP
The
.B ldap_search_ext_s()
routine is the synchronous version of
.BR ldap_search_ext().
2006-06-17 15:06:48 +08:00
.LP
It also returns a code indicating success or, in the
case of failure, indicating the nature of the failure
of the operation. See
1998-08-09 08:43:13 +08:00
.BR ldap_error (3)
for details.
.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
1998-08-09 08:43:13 +08:00
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>.
2006-06-17 15:06:48 +08:00
.SH DEPRECATED INTERFACES
The
.B ldap_search()
routine is deprecated in favor of the
.B ldap_search_ext()
routine. The
.B ldap_search_s()
and
.B ldap_search_st()
routines are deprecated in favor of the
.B ldap_search_ext_s()
routine.
.LP
.so Deprecated
1998-08-09 08:43:13 +08:00
.SH SEE ALSO
.BR ldap (3),
.BR ldap_result (3),
.BR ldap_error (3)
1998-10-25 09:41:42 +08:00
.SH ACKNOWLEDGEMENTS
2006-06-17 15:06:48 +08:00
.so ../Project