LDAP_SEARCH(3)

📦
version 2.6.16 · 21 versions
, in fedora 44

💅 LDAP_SEARCH(3) — the "go find my entries" era ✨

okay bestie, settle in, because this is the page for libldap from OpenLDAP — the one where you actually ask the directory a question and it answers. this is library functions manual territory, and honestly? iconic.

🎀 NAME 🎀

ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s — these are the routines that perform an LDAP search operation. that's the whole vibe. you want entries, they get you entries. 💖

🦋 LIBRARY 🦋

OpenLDAP LDAP — that's libldap, and you link it with -lldap. no cap.

✨ 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 );

like, yes, that's a lot of parameters. she's thorough. she knows what she wants. 👑

🌸 DESCRIPTION 🌸

so these routines are how you do LDAP search operations. full stop.

ldap_search_ext_s() is the synchronous one — meaning it does not return until the whole operation is done. she sits there, waits, and then hands you back a pointer to the resulting LDAP messages at the location pointed to by the res parameter. patient queen behavior. 🫶

ldap_search_ext() is the asynchronous version — it kicks off the search and immediately returns the message id of the operation it just initiated, tucked into the integer pointed to by the msgidp parameter. main character energy: initiates, drops the receipt, dips. 🔥

now for the deets on the parameters, bestie:

  • base — the DN of the entry at which to start the search. your starting point, your home base.
  • scope — the scope of the search. must be one of:
    • LDAP_SCOPE_BASE — search the object itself
    • LDAP_SCOPE_ONELEVEL — search the object's immediate children
    • LDAP_SCOPE_SUBTREE — search the object and all its descendants
    • LDAP_SCOPE_CHILDREN — search all of the descendants
⚠️ heads up: LDAP_SCOPE_CHILDREN requires the server to support the LDAP Subordinates Search Scope extension. no extension, no descendants. 💀
  • filter — a string representation of the filter to apply in the search. it should conform to the format specified in RFC 4515 as extended by RFC 4526. for instance, (cn=Jane Doe). and just so you know: using that extension requires the server to support the LDAP Absolute True/False Filter extension. you may also pass NULL to indicate the library should send the filter (objectClass=*). 🎀
  • attrs — a null-terminated array of attribute descriptions to return from matching entries. if you pass NULL, the return of all user attributes is requested. the description "*" (LDAP_ALL_USER_ATTRIBUTES) can be used to request all user attributes to be returned. the description "+" (LDAP_ALL_OPERATIONAL_ATTRIBUTES) can be used to request all operational attributes to be returned — note that this requires the server to support the LDAP All Operational Attribute extension. and to request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. literally just her, alone, on the list. 💅
  • attrsonly — set this to a non-zero value if you only want attribute descriptions. set it to zero (0) if you want both attribute descriptions and attribute values. pick your fighter. 🌈
  • serverctrls and clientctrls — these may be used to specify server and client controls, respectively.

and ldap_search_ext_s() is the synchronous version of ldap_search_ext(). she is also the one who returns a code indicating success — or, in the case of failure, indicating the nature of the failure of the operation. see ldap_error(3) for details. she's dramatic but she's honest. ⭐

🧚 NOTES 🧚

  • both read and list functionality are subsumed by these routines — just use a filter like (objectclass=*) with a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). one routine, so many jobs, highkey versatile. 💜
  • these routines may dynamically allocate memory. you, the caller, are responsible for freeing such memory using supplied deallocation routines. don't leave it hanging, bestie. 😭 return values are contained in <ldap.h>.
🚨 real talk: the res parameter of ldap_search_ext_s() and ldap_search_s() should be freed with ldap_msgfree() regardless of the return value of these functions. yes, even if it errored. that's not a suggestion. 🙈

💀 DEPRECATED INTERFACES 💀

gather round, we need to talk about the old ones:

  • ldap_search() is deprecated in favor of ldap_search_ext().
  • ldap_search_s() and ldap_search_st() are deprecated in favor of ldap_search_ext_s().

deprecated interfaces generally remain in the library, ngl. the macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling a program designed to use deprecated interfaces.

but fr fr: it is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. over time, it is expected that documentation (and, eventually, support) for deprecated interfaces will be eliminated. like, they're on the way out. mourn if you must, then move on. 🦋

🌟 SEE ALSO 🌟

👑 ACKNOWLEDGEMENTS 👑

OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release. give them their flowers, they earned them. 🌸🫶

and that's the page, bestie! this one shipped as part of OpenLDAP 2.6.16, dated 2026/10/21 — so go search something slay-worthy. periodt. 💖✨

📦 where this page comes from