LDAPFIRSTREFERENCE(3)                                LDAPFIRSTREFERENCE(3)



NAME
       ldapfirstreference,   ldapnextreference,   ldapcountreferences  -
       Stepping through continuation references in a result chain

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       ##include <>

       int ldapcountreferences( LDAP **ld,, LDAPessage **result )

       LDAPessage **ldapfirstreference( LDAP **ld,, LDAPessage **result )

       LDAPessage **ldapnextreference( LDAP **ld,, LDAPessage **reference )

DESCRIPTION
       These routines are used to step through the continuation references  in
       a  result  chain  received  from ldapresult(3) or the synchronous LDAP
       search operation routines.

       The ldapfirstreference() routine is used to retrieve the first refer-
       ence  message  in a result chain.  It takes the result as returned by a
       call  to  ldapresult(3),,  ldapsearchs(3)  or  ldapsearchst(3)  and
       returns a pointer to the first reference message in the result chain.

       This  pointer should be supplied on a subsequent call to ldapnextref-
       erence() to get the next reference message, the result of which  should
       be   supplied   to   the   next  call  to  ldapnextreference(),  etc.
       ldapnextreference() will return NUL when there are no more reference
       messages.  The reference messages returned from these calls are used by
       ldapparsereference(3) to extract referrals and controls.

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

ERORS
       If an error occurs in ldapfirstreference() or  ldapnextreference(),
       NUL is returned.  If an error occurs in ldapcountreferences(), -1 is
       returned.

SEE ALSO
       ldap(3), ldapresult(3), ldapsearch(3), ldapparsereference(3)

ACKNOWLEDGEMENTS
       OpenLDAP  is  developed  and  maintained  by   The   OpenLDAP   Project
       (http:/www.openldap.org/).   OpenLDAP  is  derived  from University of
       Michigan LDAP 3.3 Release.



OpenLDAP 2.2.19                   2004/11/26           LDAPFIRSTREFERENCE(3)