---
name: "ldap_first_reference"
section: "3"
platform: "linux"
package: "libldap"
version: "2.7.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/ldap_first_reference"
---

# ldap\_first\_reference(3)

Stepping through continuation references in a result chain

## NAME

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

## LIBRARY

OpenLDAP LDAP (libldap, -lldap)

## 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

**These routines are used to step through the continuation references in a** **result chain received from** [**ldap\_result**(3)](/ldap_result/3.md) **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)](/ldap_result/3.md)**,** [**ldap\_search\_s**(3)](/ldap_search_s/3.md) **or** [**ldap\_search\_st**(3)](/ldap_search_st/3.md) **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)](/ldap_parse_reference/3.md) **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

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

[**ldap**(3)](/ldap/3.md), [**ldap\_result**(3)](/ldap_result/3.md), [**ldap\_search**(3)](/ldap_search/3.md), [**ldap\_parse\_reference**(3)](/ldap_parse_reference/3.md)

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