Section 3 man pages for ldap_first_reference(), ldap_next_reference() and

ldap_count_references()

diff --git a/doc/man/man3/ldap_first_reference.3 b/doc/man/man3/ldap_first_reference.3
new file mode 100644 (file)
index 0000000..45f6afb
--- /dev/null
+++ b/doc/man/man3/ldap_first_reference.3
@@ -0,0 +1,73 @@
+.TH LDAP_FIRST_REFERENCE 3 "19 September 2001" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2001 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 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
+.B     OpenLDAP
+is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
+.B     OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.  

diff --git a/doc/man/man3/ldap_first_reference.3.links b/doc/man/man3/ldap_first_reference.3.links
new file mode 100644 (file)
index 0000000..a747bbb
--- /dev/null
+++ b/doc/man/man3/ldap_first_reference.3.links
@@ -0,0 +1,2 @@
+ldap_next_reference.3
+ldap_count_references.3