.TH LDAP_FIRST_ATTRIBUTE 3 "22 September 1998" "OpenLDAP LDVERSION"
.SH NAME
ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes
.SH SYNOPSIS
.nf
.ft B
#include <lber.h>
#include <ldap.h>
.LP
.ft B
char *ldap_first_attribute(ld, entry, berptr)
.ft
LDAP *ld;
LDAPMessage *entry;
BerElement **berptr;
.LP
.ft B
char *ldap_next_attribute(ld, entry, ber)
.ft
LDAP *ld;
LDAPMessage *entry;
BerElement *ber;
.SH DESCRIPTION
The
.B ldap_first_attribute()
and
.B ldap_next_attribute()
routines are used
to step through the attributes in an LDAP entry.
.B ldap_first_attribute()
takes an \fIentry\fP as returned by
.BR ldap_first_entry (3)
or
.BR ldap_next_entry (3)
and returns a pointer to a per-connection buffer
containing the first attribute type in the entry.  The return value
should be treated as if it is a pointer to a static area (i.e.,
.BR strdup (3)
it if you want to save it).
.LP
It also returns, in \fIberptr\fP, a pointer to a BerElement it has
allocated to keep track of its current position.  This pointer should
be passed to subsequent calls to
.B ldap_next_attribute()
and is used used
to effectively step through the entry's attributes.  This pointer
is freed by
.B ldap_next_attribute()
when there are no more attributes (that
is, when
.B ldap_next_attribute()
returns NULL).  Otherwise, the caller is
responsible for freeing the BerElement pointed to by \fIberptr\fP when
it is no longer needed by calling
.BR ber_free (3).
When calling
.BR ber_free (3)
in this instance, be sure the second argument is 0.
.LP
The attribute names returned are suitable for inclusion in a call
to
.BR ldap_get_values (3)
to retrieve the attribute's values.
.SH ERRORS
If an error occurs, NULL is returned and the ld_errno field in the
\fIld\fP parameter is set to indicate the error.  See
.BR ldap_error (3)
for a description of possible error codes.
.SH NOTES
The
.B ldap_first_attribute()
routine dyanamically allocated memory that may need to
be freed by the caller via
.BR ber_free (3).
.SH SEE ALSO
.BR ldap(3),
.BR ldap_first_entry(3),
.BR ldap_get_values(3),
.BR ldap_error(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.