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