NAME

       ldap_first_attribute, ldap_next_attribute - step through LDAP entry attributes

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

       #include <ldap.h>

       char *ldap_first_attribute(
            LDAP *ld, LDAPMessage *entry, BerElement **berptr )

       char *ldap_next_attribute(
            LDAP *ld, LDAPMessage *entry, BerElement *ber )

       int ldap_get_attribute_ber(
            LDAP *ld, LDAPMessage *entry, BerElement *ber,
            BerValue *attr, BerVarray *vals )

DESCRIPTION

       The  ldap_first_attribute(),  ldap_next_attribute()  and ldap_get_attribute_ber() routines
       are used to step through the attributes in an LDAP entry.  ldap_first_attribute() takes an
       entry  as  returned  by ldap_first_entry(3) or ldap_next_entry(3) and returns a pointer to
       character  string   containing   the   first   attribute   description   in   the   entry.
       ldap_next_attribute() returns the next attribute description in the entry.

       It  also  returns,  in berptr, a pointer to a BerElement it has allocated to keep track of
       its  current  position.   This  pointer  should  be  passed   to   subsequent   calls   to
       ldap_next_attribute() and is used to effectively step through the entry's attributes.  The
       caller is solely responsible for freeing the BerElement pointed to by berptr when it is no
       longer  needed by calling ber_free(3).  When calling ber_free(3) in this instance, be sure
       the second argument is 0.

       The attribute names returned are suitable for inclusion in a call to ldap_get_values(3) to
       retrieve the attribute's values.

       The  ldap_get_attribute_ber()  routine allows one to iterate over all attributes in-place,
       without allocating memory to hold text for the attribute name or its values, if requested.
       The  use  case  is  similar  to  ldap_next_attribute()  except  that the attribute name is
       returned into attr and, if vals is non-NULL, the list of  values  is  stored  there.  Both
       point into the LDAP message and remain valid only while the entry is valid.  The caller is
       still responsible for freeing vals with ldap_memfree(3), if used.

ERRORS

       If an error occurs, NULL is returned and the ld_errno field in the ld parameter is set  to
       indicate the error.  See ldap_error(3) for a description of possible error codes.

NOTES

       The  ldap_first_attribute()  and ldap_next_attribute() return dynamically allocated memory
       that must be freed by the caller via ldap_memfree(3).  For ldap_get_attribute_ber(),  only
       the  actual  vals  pointer needs to be freed with ldap_memfree(3), other data is accounted
       for as part of ber.

SEE ALSO

       ldap(3), ldap_first_entry(3), ldap_get_values(3), ldap_error(3)

ACKNOWLEDGEMENTS

       OpenLDAP   Software   is   developed   and   maintained   by    The    OpenLDAP    Project
       <http://www.openldap.org/>.   OpenLDAP Software is derived from the University of Michigan
       LDAP 3.3 Release.