'\" te
.TH LDAP_FIRST_REFERENCE 3 "2012/02/29" "OpenLDAP 2.4.30"
.\" $OpenLDAP$
.\" Copyright 1998-2012 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.

.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	library/openldap
=
Stability	Committed
.TE 
.PP
.SH SEE ALSO
.BR ldap (3),
.BR ldap_result (3),
.BR ldap_search (3),
.BR ldap_parse_reference (3)
.SH ACKNOWLEDGEMENTS
.\" Shared Project Acknowledgement Text
.B "OpenLDAP Software"
is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
.B "OpenLDAP Software"
is derived from University of Michigan LDAP 3.3 Release.  


.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.4.30.tgz

Further information about this software can be found on the open source community website at http://www.openldap.org/.