---
name: "ldap_search"
section: "3"
platform: "macos"
package: "OpenLDAP"
version: "561"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/ldap_search"
---

# ldap\_search(3)

Perform an LDAP search operation

## NAME

ldap\_search, ldap\_search\_s, ldap\_search\_st, ldap\_search\_ext, ldap\_search\_ext\_s - Perform an LDAP search operation

## LIBRARY

OpenLDAP LDAP (libldap, -lldap)

## SYNOPSIS

```
#include <sys/types.h>
#include <ldap.h>
```

**int ldap\_search\_ext(**

**LDAP \****ld***,** **char \****base***,** **int** *scope***,** **char \****filter***,** **char \****attrs***\[\],** **int** *attrsonly***,** **LDAPControl \*\****serverctrls***,** **LDAPControl \*\****clientctrls***,** **struct timeval \****timeout***,** **int** *sizelimit***,** **int \****msgidp* **);**

**int ldap\_search\_ext\_s(**

**LDAP \****ld***,** **char \****base***,** **int** *scope***,** **char \****filter***,** **char \****attrs***\[\],** **int** *attrsonly***,** **LDAPControl \*\****serverctrls***,** **LDAPControl \*\****clientctrls***,** **struct timeval \****timeout***,** **int** *sizelimit***,** **LDAPMessage \*\****res* **);**

## DESCRIPTION

**These routines are used to perform LDAP search operations.** **The** **ldap\_search\_ext\_s()** **routine** **does the search synchronously (i.e., not** **returning until the operation completes), providing a pointer** **to the resulting LDAP messages at the location pointed to by** **the** *res* **parameter.**

**The** **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** *msgidp* **parameter.**

**The** *base* **parameter is the DN of the entry at which to start the search.**

**The** *scope* **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.**

**The** *filter* **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=\*).**

**The** *attrs* **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.** **The description "\*" (LDAP\_ALL\_USER\_ATTRIBUTES) may be used to request** **all user attributes to be returned.** **The description "+"(LDAP\_ALL\_OPERATIONAL\_ATTRIBUTES) may be used to** **request all operational attributes to be returned.  Note that this** **requires the server to support the LDAP All Operational Attribute** **extension.** **To request no attributes, the description "1.1" (LDAP\_NO\_ATTRS)** **should be listed by itself.**

**The** *attrsonly* **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.**

**The** *serverctrls* **and** *clientctrls* **parameters may be used** **to specify server and client controls, respectively.**

**The** **ldap\_search\_ext\_s()** **routine is the synchronous version of** **ldap\_search\_ext().**

**It also returns a code indicating success or, in the** **case of failure, indicating the nature of the failure** **of the operation.  See** [**ldap\_error**(3)](/ldap_error/3.md) **for details.**

## 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\>.**

**Note that** *res* parameter of **ldap\_search\_ext\_s()** and **ldap\_search\_s()** should be freed with **ldap\_msgfree()** regardless of return value of these functions.

## DEPRECATED INTERFACES

The  **ldap\_search()** routine is deprecated in favor of the **ldap\_search\_ext()** routine.  The  **ldap\_search\_s()** and **ldap\_search\_st()** routines are deprecated in favor of the **ldap\_search\_ext\_s()** routine.

## SEE ALSO

[**ldap**(3)](/ldap/3.md), [**ldap\_result**(3)](/ldap_result/3.md), [**ldap\_error**(3)](/ldap_error/3.md)

## ACKNOWLEDGEMENTS