LDAP_OPEN(3)

💅 LDAP_OPEN(3) — the libldap glow-up you didn't know you needed

okay so first things first, bestie: this is page LDAP_OPEN(3) from the OpenLDAP LDAP library manual, and no, the filename is not a typo, the page is literally called that even though it's all about ldap_dup and ldap_destroy. iykyk. 💫

---

✨ NAME ✨

ldap_dup, ldap_destroy, — duplicating and destroying LDAP session handles, fr fr 🫶

---

📚 LIBRARY 📚

OpenLDAP LDAP (libldap, -lldap) — that's the shelf you're pulling this off of. 🎀

---

🧚 SYNOPSIS 🧚

#include <ldap.h>

LDAP *ldap_dup(
       LDAP *old );

int ldap_destroy(
       LDAP *old );

look at her. iconic. not a single wasted character. 👑

---

🌸 DESCRIPTION 🌸

So ldap_dup() duplicates an existing LDAP (LDAP *) session handle. that's it, that's the vibe. the new session handle can be used concurrently with the original session handle — like, both of them, at the same time, living their best lives. and in a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination (yes, contamination, the manpage said it, i'm not being dramatic). each session handle manages its own private error results, so nobody's stepping on anybody's feelings. 💖

ldap_destroy() destroys an existing session handle. short king. does exactly what it says.

The ldap_dup() and ldap_destroy() functions are used in conjunction with a "thread safe" version of libldap to enable operation thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling. literally the whole point. 🦋

When a session is created through the use of one of the session creation functions — including ldap_open(3), ldap_init(3), ldap_initialize(3) or ldap_init_fd(3) — an LDAP * session handle is returned to the application. the session handle may be shared amongst threads, however the error codes are unique to a session handle. so if multiple threads are performing different operations using the same session handle, you get inconsistent error codes and return values. messy. we don't like messy. 😭

To prevent this confusion, ldap_dup() is used to duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results. main character move honestly. ✨

ok important part incoming, pay attention bestie 📌

The message queues for a session are shared between sibling session handles. results of operations on sibling session handles are accessible to all the sibling session handles. so if your application wants results associated with a specific operation, provide the appropriate msgid to ldap_result(). and applications should avoid calling ldap_result() with LDAP_RES_ANY — because that may "steal" and return results in the calling thread that another operation in a different thread, using a different session handle, may require to complete. stealing is not slay in this context. 💀

When ldap_unbind() is called on a session handle with siblings, all the siblings become invalid. whole friend group cancelled. 🙈

Siblings must be destroyed using ldap_destroy(). session handle resources associated with the original (LDAP *) will be freed when the last session handle is destroyed, or when ldap_unbind() is called, if no other session handles currently exist. like a group chat that only archives once literally everyone leaves. 🎀

---

🔥 ERRORS 🔥

If an error occurs, ldap_dup() will return NULL and errno should be set appropriately. ldap_destroy() will directly return the LDAP code associated to the error (or LDAP_SUCCESS in case of success); errno should be set as well whenever appropriate. two error channels, keep up. 👑

---

🌈 SEE ALSO 🌈

• ldap_open(3)
• ldap_init(3)
• ldap_initialize(3)
• ldap_init_fd(3)
• errno(3)

go read them, i'll wait. 💜

---

🎀 ACKNOWLEDGEMENTS 🎀

This work is based on the previously proposed LDAP C API Concurrency Extensions draft (draft-zeilenga-ldap-c-api-concurrency-00.txt) effort — credits to the draft girlies. 🙏 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. history! lineage! we love a documented origin story. 🌸

---

and that's the whole page, bestie 💖 this was OpenLDAP 2.6.16, dated 2026/10/21 — screenshot it, cite it, put it on your fridge. mwah. 💅✨