ITS#8820 Document ldap_get_attribute_ber()

doc/man/man3/ldap_first_attribute.3

@@ -18,11 +18,17 @@ char *ldap_first_attribute(
 .ft B
 char *ldap_next_attribute(
 	LDAP *ld, LDAPMessage *entry, BerElement *ber )
+.LP
+.ft B
+int ldap_get_attribute_ber(
+	LDAP *ld, LDAPMessage *entry, BerElement *ber,
+	BerValue *attr, BerVarray *vals )
 .SH DESCRIPTION
 The
-.B ldap_first_attribute()
-and
+.BR ldap_first_attribute() ,
 .B ldap_next_attribute()
+and
+.B ldap_get_attribute_ber()
 routines are used
 to step through the attributes in an LDAP entry.
 .B ldap_first_attribute()
@@ -52,6 +58,19 @@ The attribute names returned are suitable for inclusion in a call
 to
 .BR ldap_get_values (3)
 to retrieve the attribute's values.
+.LP
+The
+.B 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
+.B ldap_next_attribute()
+except that the attribute name is returned into \fIattr\fP and, if
+\fIvals\fP 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 \fIvals\fP with
+.BR ldap_memfree (3),
+if used.
 .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
@@ -63,7 +82,12 @@ The
 and
 .B ldap_next_attribute()
 return dynamically allocated memory that must be freed by the caller via
-.BR ldap_memfree (3).   
+.BR ldap_memfree (3).
+For
+.BR ldap_get_attribute_ber() ,
+only the actual \fIvals\fP pointer needs to be freed with
+.BR ldap_memfree (3),
+other data is accounted for as part of \fIber\fP.
 .SH SEE ALSO
 .BR ldap (3),
 .BR ldap_first_entry (3),

doc/man/man3/ldap_first_attribute.3.links

@@ -1 +1,2 @@
 ldap_next_attribute.3
+ldap_get_attribute_ber.3