LDAP\_OPEN(3) Library Functions Manual LDAP\_OPEN(3)

# [NAME](#NAME)

ldap\_dup, ldap\_destroy, - Duplicate and destroy LDAP session handles

# [LIBRARY](#LIBRARY)

OpenLDAP LDAP (libldap, -lldap)

# [SYNOPSIS](#SYNOPSIS)

```
#include <ldap.h>
```

```
LDAP *ldap_dup(
```

```
LDAP *old );
```

```
int ldap_destroy(
```

```
LDAP *old );
```

# [DESCRIPTION](#DESCRIPTION)

**ldap\_dup()** duplicates an existing LDAP (**LDAP \***) session handle. The new session handle may be used concurrently with the original session handle. In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination. Each session handle manages its own private error results.

**ldap\_destroy()** destroys an existing session handle.

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.

When a session is created through the use of one of the session creation functions including [**ldap\_open**(3)](/man/enterprise-packages/openldap-2.5/ldap_open.3), [**ldap\_init**(3)](/man/enterprise-packages/openldap-2.5/ldap_init.3), [**ldap\_initialize**(3)](/man/enterprise-packages/openldap-2.5/ldap_initialize.3) or [**ldap\_init\_fd**(3)](/man/enterprise-packages/openldap-2.5/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. Multiple threads performing different operations using the same session handle will result in inconsistent error codes and return values.

To prevent this confusion, **ldap\_dup()** is used duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results.

The message queues for a session are shared between sibling session handles. Results of operations on a sibling session handles are accessible to all the sibling session handles. Applications desiring results associated with a specific operation should provide the appropriate msgid to **ldap\_result()**. Applications should avoid calling **ldap\_result()** with **LDAP\_RES\_ANY** as 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.

When **ldap\_unbind()** is called on a session handle with siblings, all the siblings become invalid.

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.

# [ERRORS](#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.

# [SEE ALSO](#SEE_ALSO)

[**ldap\_open**(3)](/man/enterprise-packages/openldap-2.5/ldap_open.3), [**ldap\_init**(3)](/man/enterprise-packages/openldap-2.5/ldap_init.3), [**ldap\_initialize**(3)](/man/enterprise-packages/openldap-2.5/ldap_initialize.3), [**ldap\_init\_fd**(3)](/man/enterprise-packages/openldap-2.5/ldap_init_fd.3), [**errno**(3)](/man/enterprise-packages/openldap-2.5/errno.3)

# [ACKNOWLEDGEMENTS](#ACKNOWLEDGEMENTS)

This work is based on the previously proposed **LDAP C API Concurrency Extensions** draft **(**draft-zeilenga-ldap-c-api-concurrency-00.txt**)** effort. **OpenLDAP Software** is developed and maintained by The OpenLDAP Project &lt;http://www.openldap.org/&gt;. **OpenLDAP Software** is derived from the University of Michigan LDAP 3.3 Release.

2025/05/22 OpenLDAP 2.5.20

---

Document: ldap_destroy(3) from openldap-2.5 2.5.20-r6 (Chainguard OS)
Source: https://git.openldap.org/openldap/openldap.git