LDAP\_FIRST\_REFERENCE(3) Library Functions Manual LDAP\_FIRST\_REFERENCE(3)

# [NAME](#NAME)

ldap\_first\_reference, ldap\_next\_reference, ldap\_count\_references - Stepping through continuation references in a result chain

# [LIBRARY](#LIBRARY)

OpenLDAP LDAP (libldap, -lldap)

# [SYNOPSIS](#SYNOPSIS)

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

```
int ldap_count_references( LDAP *ld, LDAPMessage *result )
```

```
LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result )
```

```
LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference )
```

# [DESCRIPTION](#DESCRIPTION)

These routines are used to step through the continuation references in a result chain received from [**ldap\_result**(3)](/man/os/openldap-2.7/ldap_result.3) or the synchronous LDAP search operation routines.

The **ldap\_first\_reference()** routine is used to retrieve the first reference message in a result chain. It takes the *result* as returned by a call to [**ldap\_result**(3)](/man/os/openldap-2.7/ldap_result.3)**,** [**ldap\_search\_s**(3)](/man/os/openldap-2.7/ldap_search_s.3) or [**ldap\_search\_st**(3)](/man/os/openldap-2.7/ldap_search_st.3) and returns a pointer to the first reference message in the result chain.

This pointer should be supplied on a subsequent call to **ldap\_next\_reference()** to get the next reference message, the result of which should be supplied to the next call to **ldap\_next\_reference()**, etc. **ldap\_next\_reference()** will return NULL when there are no more reference messages. The reference messages returned from these calls are used by [**ldap\_parse\_reference**(3)](/man/os/openldap-2.7/ldap_parse_reference.3) to extract referrals and controls.

A count of the number of reference messages in the search result can be obtained by calling **ldap\_count\_references()**. It can also be used to count the number of reference messages remaining in a result chain.

# [ERRORS](#ERRORS)

If an error occurs in **ldap\_first\_reference()** or **ldap\_next\_reference()**, NULL is returned. If an error occurs in **ldap\_count\_references()**, -1 is returned.

# [SEE ALSO](#SEE_ALSO)

[**ldap**(3)](/man/os/openldap-2.7/ldap.3), [**ldap\_result**(3)](/man/os/openldap-2.7/ldap_result.3), [**ldap\_search**(3)](/man/os/openldap-2.7/ldap_search.3), [**ldap\_parse\_reference**(3)](/man/os/openldap-2.7/ldap_parse_reference.3)

# [ACKNOWLEDGEMENTS](#ACKNOWLEDGEMENTS)

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

2026/09/08 OpenLDAP 2.7.1

---

Document: ldap_next_reference(3) from openldap-2.7 2.7.1-r1 (Chainguard OS)
Source: https://github.com/openldap/openldap.git