1 files changed, 71 insertions, 0 deletions
diff --git a/doc/man/man3/ldap_first_reference.3 b/doc/man/man3/ldap_first_reference.3
new file mode 100644
index 0000000..2bcba1a
--- /dev/null
+++ b/doc/man/man3/ldap_first_reference.3
@@ -0,0 +1,71 @@
+.TH LDAP_FIRST_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.SH NAME
+ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain
+.SH LIBRARY
+OpenLDAP LDAP (libldap, \-lldap)
+.SH SYNOPSIS
+.nf
+.ft B
+#include <ldap.h>
+.LP
+.ft B
+int ldap_count_references( LDAP *ld, LDAPMessage *result )
+.LP
+.ft B
+LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result )
+.LP
+.ft B
+LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference )
+.SH DESCRIPTION
+.LP
+These routines are used to step through the continuation references in a
+result chain received from
+.BR ldap_result (3)
+or the synchronous LDAP search operation routines.
+.LP
+The
+.B ldap_first_reference()
+routine is used to retrieve the first reference message in a
+result chain.  It takes the \fIresult\fP as returned by a call to
+.BR ldap_result (3) ,
+.BR ldap_search_s (3)
+or
+.BR ldap_search_st (3)
+and returns a pointer to the first reference message in the
+result chain.
+.LP
+This pointer should be supplied on a subsequent call to
+.B ldap_next_reference()
+to get the next reference message, the result of which should be
+supplied to the next call to
+.BR ldap_next_reference() ,
+etc.
+.B ldap_next_reference()
+will return NULL when there are no more reference messages.
+The reference messages returned from these calls are used by
+.BR ldap_parse_reference (3)
+to extract referrals and controls.
+.LP
+A count of the number of reference messages in the search result can be
+obtained by calling
+.BR ldap_count_references() .
+It can also be used to count the number of reference messages remaining
+in a result chain.
+.SH ERRORS
+If an error occurs in
+.B ldap_first_reference()
+or
+.BR ldap_next_reference() ,
+NULL is returned.  If an error occurs in
+.BR ldap_count_references() ,
+-1 is returned.
+.SH SEE ALSO
+.BR ldap (3),
+.BR ldap_result (3),
+.BR ldap_search (3),
+.BR ldap_parse_reference (3)
+.SH ACKNOWLEDGEMENTS
+.so ../Project