1.lf 1 stdin
2.TH LDAP_SEARCH 3 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
5.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
6.SH NAME
7ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation
8.SH LIBRARY
9OpenLDAP LDAP (libldap, \-lldap)
10.SH SYNOPSIS
11.nf
12.ft B
13#include <sys/types.h>
14#include <ldap.h>
15.LP
16.ft B
17int ldap_search_ext(
18.RS
19LDAP *\fIld\fB,
20char *\fIbase\fB,
21int \fIscope\fB,
22char *\fIfilter\fB,
23char *\fIattrs\fB[],
24int \fIattrsonly\fB,
25LDAPControl **\fIserverctrls\fB,
26LDAPControl **\fIclientctrls\fB,
27struct timeval *\fItimeout\fB,
28int \fIsizelimit\fB,
29int *\fImsgidp\fB );
30.RE
31.LP
32.ft B
33int ldap_search_ext_s(
34.RS
35LDAP *\fIld\fB,
36char *\fIbase\fB,
37int \fIscope\fB,
38char *\fIfilter\fB,
39char *\fIattrs\fB[],
40int \fIattrsonly\fB,
41LDAPControl **\fIserverctrls\fB,
42LDAPControl **\fIclientctrls\fB,
43struct timeval *\fItimeout\fB,
44int \fIsizelimit\fB,
45LDAPMessage **\fIres\fB );
46.RE
47.SH DESCRIPTION
48These routines are used to perform LDAP search operations.
49The
50.B ldap_search_ext_s()
51routine
52does the search synchronously (i.e., not
53returning until the operation completes), providing a pointer
54to the resulting LDAP messages at the location pointed to by
55the \fIres\fP parameter.
56.LP
57The
58.B ldap_search_ext()
59routine is the asynchronous version, initiating the search and returning
60the message id of the operation it initiated in the integer
61pointed to by the \fImsgidp\fP parameter.
62.LP
63The \fIbase\fP parameter is the DN of the entry at which to start the search.
64.LP
65The \fIscope\fP parameter is the scope of the search and should be one
66of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL,
67to search the object's immediate children, LDAP_SCOPE_SUBTREE, to
68search the object and all its descendants, or LDAP_SCOPE_CHILDREN,
69to search all of the descendants.   Note that the latter requires
70the server support the LDAP Subordinates Search Scope extension.
71.LP
72The \fIfilter\fP is a string representation of the filter to
73apply in the search.  The string should conform to the format
74specified in RFC 4515 as extended by RFC 4526.  For instance,
75"(cn=Jane Doe)".  Note that use of the extension requires the
76server to support the LDAP Absolute True/False Filter extension.
77NULL may be specified to indicate the library should send the
78filter (objectClass=*).
79.LP
80The \fIattrs\fP parameter is a null-terminated array of attribute
81descriptions to return from matching entries.
82If NULL is specified, the return of all user attributes is requested.
83The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
84all user attributes to be returned.
85The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to
86request all operational attributes to be returned.  Note that this
87requires the server to support the LDAP All Operational Attribute
88extension.
89To request no attributes, the description "1.1" (LDAP_NO_ATTRS)
90should be listed by itself.
91.LP
92The \fIattrsonly\fP parameter should be set to a non-zero value
93if only attribute descriptions are wanted.  It should be set to zero (0)
94if both attributes descriptions and attribute values are wanted.
95.LP
96The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used
97to specify server and client controls, respectively.
98.LP
99The
100.B ldap_search_ext_s()
101routine is the synchronous version of
102.BR ldap_search_ext().
103.LP
104It also returns a code indicating success or, in the
105case of failure, indicating the nature of the failure
106of the operation.  See
107.BR ldap_error (3)
108for details.
109.SH NOTES
110Note that both read
111and list functionality are subsumed by these routines,
112by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to
113emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
114.LP
115These routines may dynamically allocate memory. The caller is
116responsible for freeing such memory using supplied deallocation
117routines. Return values are contained in <ldap.h>.
118.LP
119Note that \fIres\fR parameter of
120.B ldap_search_ext_s()
121and
122.B ldap_search_s()
123should be freed with
124.B ldap_msgfree()
125regardless of return value of these functions.
126.SH DEPRECATED INTERFACES
127The 
128.B ldap_search()
129routine is deprecated in favor of the
130.B ldap_search_ext()
131routine.  The 
132.B ldap_search_s()
133and
134.B ldap_search_st()
135routines are deprecated in favor of the
136.B ldap_search_ext_s()
137routine.
138.LP
139.lf 1 ./Deprecated
140Deprecated interfaces generally remain in the library.  The macro
141LDAP_DEPRECATED can be defined to a non-zero value
142(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use
143deprecated interfaces.  It is recommended that developers writing new
144programs, or updating old programs, avoid use of deprecated interfaces.
145Over time, it is expected that documentation (and, eventually, support) for
146deprecated interfaces to be eliminated.
147.lf 139 stdin
148.SH SEE ALSO
149.BR ldap (3),
150.BR ldap_result (3),
151.BR ldap_error (3)
152.SH ACKNOWLEDGEMENTS
153.lf 1 ./../Project
154.\" Shared Project Acknowledgement Text
155.B "OpenLDAP Software"
156is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
157.B "OpenLDAP Software"
158is derived from the University of Michigan LDAP 3.3 Release.  
159.lf 145 stdin
160