LDAPFIRSTMESAGE(3)                                    LDAPFIRSTMESAGE(3)



NAME
       ldapfirstmessage,  ldapnextmessage,  ldapcountmessages - Stepping
       through messages in a result chain

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       ##include <>

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

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

       LDAPessage **ldapnextmessage( LDAP **ld,, LDAPessage **message )

DESCRIPTION
       These routines are used to step through the messages in a result  chain
       received  from ldapresult(3).  For search operations, the result chain
       can contain referral, entry and result  messages.  The  ldapmsgtype(3)
       function  can  be  used  to  distinguish  between the different message
       types.

       The ldapfirstmessage() routine is used to retrieve the first  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 message in the result chain.

       This  pointer should be supplied on a subsequent call to ldapnextmes-
       sage() to get the next message, the result of which should be  supplied
       to the next call to ldapnextmessage(), etc.  ldapnextmessage() will
       return NUL when there are no more messages.

       These   functions    are    useful    when    using    routines    like
       ldapparseresult(3)  that  only  operate  on  the  first result in the
       chain.

       A count of the number of messages in the result chain can  be  obtained
       by  calling  ldapcountmessages().   It  can also be used to count the
       number of remaining messages in a chain if called with a message, entry
       or  reference  returned by ldapfirstmessage() ,, ldapnextmessage() ,,
       ldapfirstentry(3),,    ldapnextentry(3),,    ldapfirstreference(3),,
       ldapnextreference(3).

ERORS
       If an error occurs in ldapfirstmessage() or ldapnextmessage(), NUL
       is returned.  If  an  error  occurs  in  ldapcountmessages(),  -1  is
       returned.

SEE ALSO
       ldap(3),    ldapsearch(3),    ldapresult(3),    ldapparseresult(3),
       ldapfirstentry(3), ldapfirstreference(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             LDAPFIRSTMESAGE(3)